nestjs-tenant-shield 0.1.0

package/dist/context/run-with-tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-tenant.js","sourceRoot":"","sources":["../../src/context/run-with-tenant.ts"],"names":[],"mappings":";;AA6BA,sCAOC;AAwDD,4CAEC;AA9FD,qEAAgE;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,aAAa,CAC3B,QAAgB,EAChB,EAAoB;IAEpB,gDAAgD;IAChD,iDAAiD;IACjD,OAAO,6CAAoB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,SAAgB,gBAAgB,CAAI,EAAoB;IACtD,OAAO,6CAAoB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC"}

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

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { TenantContext } from '../interfaces/tenant-context.interface';
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 이 라이브러리의 심장.
+ *
+ * Node.js의 AsyncLocalStorage를 활용해서, "지금 처리 중인 요청이
+ * 어느 tenant 것인지"를 비동기 호출 체인 전체에 걸쳐 안전하게
+ * 추적합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [비유]
+ * 사무실에 동시에 여러 손님이 방문해도, 각자 손에 출입 카드를
+ * 들고 있어서 어느 부서로 안내해야 하는지 직원이 헷갈리지 않습니다.
+ * AsyncLocalStorage는 그 "출입 카드"의 역할입니다.
+ *
+ * Node.js는 동시 요청을 단일 스레드에서 비동기로 처리하기 때문에,
+ * 단순히 전역 변수에 tenantId를 넣으면 A요청 처리 중에 B요청이
+ * 끼어들어 값이 섞입니다. AsyncLocalStorage는 각 비동기 흐름에
+ * 별도의 "상자"를 부여해 이 문제를 원천 차단합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 패턴]
+ *   tenantContextStorage.run({ tenantId: 'A' }, async () => {
+ *     // 이 콜백 안에서는, 그리고 그 안에서 호출되는 모든 비동기
+ *     // 함수에서는 getStore()가 { tenantId: 'A' }를 반환합니다.
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+/**
+ * 라이브러리 전체에서 공유되는 단 하나의 AsyncLocalStorage 인스턴스.
+ *
+ * 이걸 여러 개 만들면 컨텍스트가 분리되어버려 의도와 다르게 동작합니다.
+ * 따라서 module-level singleton으로 export 합니다.
+ *
+ * ⚠️ 외부 사용자는 직접 접근하지 말고 runWithTenant() 같은 헬퍼를 쓰세요.
+ *    이 export는 라이브러리 내부 모듈들 간의 협업과 고급 디버깅용입니다.
+ */
+export declare const tenantContextStorage: AsyncLocalStorage<TenantContext>;
+//# sourceMappingURL=tenant-context.storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.storage.d.ts","sourceRoot":"","sources":["../../src/context/tenant-context.storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,kCAAyC,CAAC"}

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tenantContextStorage = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 이 라이브러리의 심장.
+ *
+ * Node.js의 AsyncLocalStorage를 활용해서, "지금 처리 중인 요청이
+ * 어느 tenant 것인지"를 비동기 호출 체인 전체에 걸쳐 안전하게
+ * 추적합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [비유]
+ * 사무실에 동시에 여러 손님이 방문해도, 각자 손에 출입 카드를
+ * 들고 있어서 어느 부서로 안내해야 하는지 직원이 헷갈리지 않습니다.
+ * AsyncLocalStorage는 그 "출입 카드"의 역할입니다.
+ *
+ * Node.js는 동시 요청을 단일 스레드에서 비동기로 처리하기 때문에,
+ * 단순히 전역 변수에 tenantId를 넣으면 A요청 처리 중에 B요청이
+ * 끼어들어 값이 섞입니다. AsyncLocalStorage는 각 비동기 흐름에
+ * 별도의 "상자"를 부여해 이 문제를 원천 차단합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 패턴]
+ *   tenantContextStorage.run({ tenantId: 'A' }, async () => {
+ *     // 이 콜백 안에서는, 그리고 그 안에서 호출되는 모든 비동기
+ *     // 함수에서는 getStore()가 { tenantId: 'A' }를 반환합니다.
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+/**
+ * 라이브러리 전체에서 공유되는 단 하나의 AsyncLocalStorage 인스턴스.
+ *
+ * 이걸 여러 개 만들면 컨텍스트가 분리되어버려 의도와 다르게 동작합니다.
+ * 따라서 module-level singleton으로 export 합니다.
+ *
+ * ⚠️ 외부 사용자는 직접 접근하지 말고 runWithTenant() 같은 헬퍼를 쓰세요.
+ *    이 export는 라이브러리 내부 모듈들 간의 협업과 고급 디버깅용입니다.
+ */
+exports.tenantContextStorage = new node_async_hooks_1.AsyncLocalStorage();
+//# sourceMappingURL=tenant-context.storage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.storage.js","sourceRoot":"","sources":["../../src/context/tenant-context.storage.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAGrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACU,QAAA,oBAAoB,GAAG,IAAI,oCAAiB,EAAiB,CAAC"}

package/dist/decorators/cacheable.decorator.d.ts

@@ -0,0 +1,27 @@
+import { CacheableOptions } from '../interfaces/cacheable-options.interface';
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @Cacheable() — 메서드 결과를 캐시 + tenant 단위 자동 분리.
+ *
+ * 일반 캐시 데코레이터의 가장 큰 함정은 "캐시 키가 tenant 간 공유돼서
+ * A학원이 요청한 결과를 B학원이 받는" 사고입니다.
+ * 이 데코레이터는 tenantScoped: true 시 키에 tenant ID prefix를
+ * 자동으로 붙여 그 위험을 차단합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시]
+ *
+ *   @Cacheable({ ttl: 300, tenantScoped: true })
+ *   async getStudentRoster() {
+ *     return this.repo.find();
+ *   }
+ *
+ *   // 캐시 키 예: "academy-A:StudentsService.getStudentRoster:[]"
+ *   //            "academy-B:StudentsService.getStudentRoster:[]"
+ *   // → 서로 절대 섞이지 않음.
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare function Cacheable(options: CacheableOptions): MethodDecorator;
+//# sourceMappingURL=cacheable.decorator.d.ts.map

package/dist/decorators/cacheable.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheable.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/cacheable.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAK7E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA2DpE"}

package/dist/decorators/cacheable.decorator.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cacheable = Cacheable;
+const get_current_tenant_id_1 = require("../context/get-current-tenant-id");
+const cache_registry_1 = require("../cache/cache.registry");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @Cacheable() — 메서드 결과를 캐시 + tenant 단위 자동 분리.
+ *
+ * 일반 캐시 데코레이터의 가장 큰 함정은 "캐시 키가 tenant 간 공유돼서
+ * A학원이 요청한 결과를 B학원이 받는" 사고입니다.
+ * 이 데코레이터는 tenantScoped: true 시 키에 tenant ID prefix를
+ * 자동으로 붙여 그 위험을 차단합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시]
+ *
+ *   @Cacheable({ ttl: 300, tenantScoped: true })
+ *   async getStudentRoster() {
+ *     return this.repo.find();
+ *   }
+ *
+ *   // 캐시 키 예: "academy-A:StudentsService.getStudentRoster:[]"
+ *   //            "academy-B:StudentsService.getStudentRoster:[]"
+ *   // → 서로 절대 섞이지 않음.
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+function Cacheable(options) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const className = target.constructor?.name ?? 'UnknownClass';
+        // dev 환경에서 fallback 사용 시 1회만 안내 — 디버깅 부담 완화.
+        let fallbackWarned = false;
+        descriptor.value = async function (...args) {
+            // 1) 캐시 서비스 인스턴스 lookup — 두 경로 시도:
+            //    (a) 사용자 클래스에 명시적으로 주입된 this.cacheService (우선)
+            //    (b) TenantShieldModule이 bootstrap 시 등록한 글로벌 registry (fallback)
+            //
+            //    (b)가 동작하려면 AppModule이 TenantShieldModule.forRoot()를
+            //    import 했고, 앱이 onApplicationBootstrap 라이프사이클을 지난 상태여야 함.
+            const explicit = this.cacheService;
+            const cacheService = explicit ?? (0, cache_registry_1.getGlobalCache)();
+            if (!cacheService) {
+                // 둘 다 없으면 캐시를 그냥 우회 — 기능적으로는 안전(원본 결과 반환).
+                // 다만 사용자가 @Cacheable을 명시했다는 건 캐시를 원했다는 뜻이므로
+                // 개발 환경에서 한 번만 경고 로그를 남겨 디버깅을 도와줍니다.
+                if (!fallbackWarned && process.env.NODE_ENV !== 'production') {
+                    fallbackWarned = true;
+                    // eslint-disable-next-line no-console
+                    console.warn(`[nestjs-tenant-shield] @Cacheable이 적용된 ${className}.${String(propertyKey)}가 ` +
+                        `캐시 인스턴스를 찾지 못해 원본 호출로 fallback 합니다. ` +
+                        `TenantShieldModule.forRoot() import 여부 또는 cacheService 주입을 확인하세요.`);
+                }
+                return originalMethod.apply(this, args);
+            }
+            // 2) 캐시 키 생성.
+            const key = buildCacheKey({
+                className,
+                methodName: String(propertyKey),
+                args,
+                options,
+            });
+            // 3) 캐시 hit → 즉시 반환
+            const cached = await cacheService.get(key);
+            if (cached !== undefined)
+                return cached;
+            // 4) Miss → 원본 실행 → 결과 저장 → 반환
+            const result = await originalMethod.apply(this, args);
+            await cacheService.set(key, result, options.ttl);
+            return result;
+        };
+        return descriptor;
+    };
+}
+/**
+ * 캐시 키를 만드는 헬퍼.
+ *
+ * 기본 키 포맷:
+ *   `[${tenantId}:]${ClassName}.${methodName}:${JSON.stringify(args)}`
+ *
+ * keyGenerator가 옵션에 있으면 args 부분은 그것을 그대로 사용.
+ */
+function buildCacheKey(input) {
+    const { className, methodName, args, options } = input;
+    // 1) tenant prefix
+    const tenantPrefix = options.tenantScoped ? `${(0, get_current_tenant_id_1.getCurrentTenantId)() ?? 'no-tenant'}:` : '';
+    // 2) args 직렬화
+    //    커스텀 keyGenerator가 있으면 우선 사용 — 사용자가 키 충돌/길이 제어 가능.
+    const argsKey = options.keyGenerator
+        ? options.keyGenerator(args)
+        : safeStringify(args);
+    return `${tenantPrefix}${className}.${methodName}:${argsKey}`;
+}
+/**
+ * 인자가 순환 참조이거나 Date 등 직렬화가 까다로운 경우에도 죽지 않게.
+ * 일단 try/catch로 감싸고, 실패 시 인자 타입 정보만 활용.
+ */
+function safeStringify(args) {
+    try {
+        return JSON.stringify(args);
+    }
+    catch {
+        return `[unserializable:${args.length}args]`;
+    }
+}
+//# sourceMappingURL=cacheable.decorator.js.map

package/dist/decorators/cacheable.decorator.js.map

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

package/dist/decorators/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 라이브러리가 제공하는 모든 데코레이터.
+ *
+ *  - @RequireTenant : tenant 컨텍스트 강제
+ *  - @SystemAction  : 의도적 tenant 없는 작업
+ *  - @Cacheable     : tenant 분리 캐시
+ *  - @TenantContext : 큐 작업 컨텍스트 복원 (v0.2)
+ */
+export * from './require-tenant.decorator';
+export * from './system-action.decorator';
+export * from './cacheable.decorator';
+export * from './tenant-context.decorator';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/decorators/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 });
+/**
+ * 라이브러리가 제공하는 모든 데코레이터.
+ *
+ *  - @RequireTenant : tenant 컨텍스트 강제
+ *  - @SystemAction  : 의도적 tenant 없는 작업
+ *  - @Cacheable     : tenant 분리 캐시
+ *  - @TenantContext : 큐 작업 컨텍스트 복원 (v0.2)
+ */
+__exportStar(require("./require-tenant.decorator"), exports);
+__exportStar(require("./system-action.decorator"), exports);
+__exportStar(require("./cacheable.decorator"), exports);
+__exportStar(require("./tenant-context.decorator"), exports);
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;GAOG;AACH,6DAA2C;AAC3C,4DAA0C;AAC1C,wDAAsC;AACtC,6DAA2C"}

package/dist/decorators/require-tenant.decorator.d.ts

@@ -0,0 +1,41 @@
+import { RequireTenantOptions } from '../interfaces/require-tenant-options.interface';
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @RequireTenant() — 이 라이브러리의 얼굴 마담 데코레이터.
+ *
+ * 클래스 또는 메서드에 붙이면, 해당 메서드를 호출할 때마다
+ * AsyncLocalStorage에 tenant 컨텍스트가 있는지 자동으로 확인합니다.
+ * 없으면 MissingTenantContextError를 throw하여 데이터 누출을 사전 차단.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 패턴 1 — 클래스 레벨]
+ *
+ *   @Injectable()
+ *   @RequireTenant()           // 이 서비스의 모든 public 메서드 보호
+ *   export class StudentsService {
+ *     async findAll() { ... }   // 자동 보호
+ *     async findOne(id) { ... } // 자동 보호
+ *   }
+ *
+ * [사용 패턴 2 — 메서드 레벨]
+ *
+ *   @Injectable()
+ *   export class MixedService {
+ *     @RequireTenant()
+ *     async findStudents() { ... }     // 보호
+ *
+ *     async getPublicStats() { ... }   // 보호 안 됨 (공개 통계 등)
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [구현 메모]
+ *  - reflect-metadata로 메타데이터를 박아두면 Subscriber가 "이 호출이
+ *    보호 대상인지" 알 수 있습니다.
+ *  - 메서드 디스크립터를 감싸서 실제 호출 직전 컨텍스트를 검사.
+ *  - 클래스 데코레이터로 쓰면 prototype의 모든 메서드를 자동 순회.
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare function RequireTenant(options?: RequireTenantOptions): MethodDecorator & ClassDecorator;
+//# sourceMappingURL=require-tenant.decorator.d.ts.map

package/dist/decorators/require-tenant.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-tenant.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/require-tenant.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gDAAgD,CAAC;AAOtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,aAAa,CAC3B,OAAO,GAAE,oBAAyB,GACjC,eAAe,GAAG,cAAc,CA0ClC"}

package/dist/decorators/require-tenant.decorator.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequireTenant = RequireTenant;
+const get_current_tenant_id_1 = require("../context/get-current-tenant-id");
+const tenant_context_storage_1 = require("../context/tenant-context.storage");
+const missing_tenant_context_error_1 = require("../errors/missing-tenant-context.error");
+const constants_1 = require("../constants");
+const options_registry_1 = require("../options/options.registry");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @RequireTenant() — 이 라이브러리의 얼굴 마담 데코레이터.
+ *
+ * 클래스 또는 메서드에 붙이면, 해당 메서드를 호출할 때마다
+ * AsyncLocalStorage에 tenant 컨텍스트가 있는지 자동으로 확인합니다.
+ * 없으면 MissingTenantContextError를 throw하여 데이터 누출을 사전 차단.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 패턴 1 — 클래스 레벨]
+ *
+ *   @Injectable()
+ *   @RequireTenant()           // 이 서비스의 모든 public 메서드 보호
+ *   export class StudentsService {
+ *     async findAll() { ... }   // 자동 보호
+ *     async findOne(id) { ... } // 자동 보호
+ *   }
+ *
+ * [사용 패턴 2 — 메서드 레벨]
+ *
+ *   @Injectable()
+ *   export class MixedService {
+ *     @RequireTenant()
+ *     async findStudents() { ... }     // 보호
+ *
+ *     async getPublicStats() { ... }   // 보호 안 됨 (공개 통계 등)
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [구현 메모]
+ *  - reflect-metadata로 메타데이터를 박아두면 Subscriber가 "이 호출이
+ *    보호 대상인지" 알 수 있습니다.
+ *  - 메서드 디스크립터를 감싸서 실제 호출 직전 컨텍스트를 검사.
+ *  - 클래스 데코레이터로 쓰면 prototype의 모든 메서드를 자동 순회.
+ * ─────────────────────────────────────────────────────────────
+ */
+function RequireTenant(options = {}) {
+    return function (target, propertyKey, descriptor) {
+        // ─────────────────────────────────────────────
+        // CASE 1: 메서드 데코레이터로 사용된 경우
+        // propertyKey와 descriptor가 모두 존재함.
+        // ─────────────────────────────────────────────
+        if (propertyKey && descriptor) {
+            wrapMethod(propertyKey, descriptor, options);
+            return descriptor;
+        }
+        // ─────────────────────────────────────────────
+        // CASE 2: 클래스 데코레이터로 사용된 경우
+        // propertyKey가 undefined이고, target이 클래스 생성자.
+        // 클래스의 prototype에 있는 모든 메서드를 자동으로 감쌉니다.
+        // ─────────────────────────────────────────────
+        const proto = target.prototype;
+        for (const key of Object.getOwnPropertyNames(proto)) {
+            // constructor는 건너뛰기.
+            if (key === 'constructor')
+                continue;
+            const desc = Object.getOwnPropertyDescriptor(proto, key);
+            // 함수가 아닌 속성(getter 등)은 건너뜀.
+            if (!desc || typeof desc.value !== 'function')
+                continue;
+            // @SystemAction()이 붙은 메서드는 의도적으로 보호 제외.
+            const isSystemAction = Reflect.getMetadata(constants_1.SYSTEM_ACTION_METADATA, desc.value);
+            if (isSystemAction)
+                continue;
+            wrapMethod(key, desc, options);
+            // 변경된 descriptor 적용.
+            Object.defineProperty(proto, key, desc);
+        }
+        return target;
+    };
+}
+/**
+ * 메서드 디스크립터를 감싸 호출 전 tenant 컨텍스트를 검사하도록 변환합니다.
+ *
+ * 이 함수가 실질적인 보호 로직의 코어입니다.
+ */
+function wrapMethod(propertyKey, descriptor, options) {
+    // 원본 메서드 백업.
+    const originalMethod = descriptor.value;
+    // 이 메서드가 @RequireTenant로 보호된다는 메타데이터 기록.
+    // Subscriber나 디버깅 도구가 참조할 수 있습니다.
+    Reflect.defineMetadata(constants_1.REQUIRE_TENANT_METADATA, options, originalMethod);
+    // 메서드를 감싸기 — 화살표 함수가 아니라 일반 함수로 작성하여
+    // `this`가 호출 시점의 인스턴스로 정상 바인딩되도록 합니다.
+    descriptor.value = async function (...args) {
+        const store = tenant_context_storage_1.tenantContextStorage.getStore();
+        const tenantId = (0, get_current_tenant_id_1.getCurrentTenantId)();
+        // 런타임 컨텍스트 플래그: runWithoutTenant()로 진입한 경우.
+        const isSystemActionRuntime = store?.isSystemAction === true;
+        // 데코레이터 메타데이터 플래그: @SystemAction()이 originalMethod에 붙은 경우.
+        // 올바른 적용 순서(@RequireTenant 위, @SystemAction 아래)일 때만 유효하다.
+        const isSystemActionDecorated = Reflect.getMetadata(constants_1.SYSTEM_ACTION_METADATA, originalMethod) === true;
+        // forRoot.allowSystemActions: true일 때만 데코레이터 우회 허용.
+        const globalAllowSystemActions = (0, options_registry_1.getGlobalOptions)()?.allowSystemActions ?? false;
+        const shouldBypass = isSystemActionRuntime || (isSystemActionDecorated && globalAllowSystemActions);
+        if (!tenantId && !options.allowSystem && !shouldBypass) {
+            // strictMode가 명시적으로 false면 경고만 남기고 통과,
+            // 그 외에는 (기본 true) 즉시 throw.
+            const strict = options.strictMode !== false;
+            if (strict) {
+                throw new missing_tenant_context_error_1.MissingTenantContextError(`@RequireTenant: tenant 컨텍스트 없음 — "${String(propertyKey)}" 호출 전 확인:\n` +
+                    `  1) TenantContextMiddleware가 이 라우트에 적용됐는지\n` +
+                    `  2) 테스트라면 runWithTenant()로 감쌌는지\n` +
+                    `  3) 시스템 작업이라면 @SystemAction + forRoot({ allowSystemActions: true }) 조합인지`, 'decorator');
+            }
+            else {
+                // TODO: forRoot에서 받은 logger 인스턴스로 경고 출력.
+                // (의도적으로 console 직접 호출은 피함 — 로거 인스턴스 주입 예정)
+            }
+        }
+        // 원본 메서드 실행 결과 반환.
+        return originalMethod.apply(this, args);
+    };
+}
+//# sourceMappingURL=require-tenant.decorator.js.map

package/dist/decorators/require-tenant.decorator.js.map

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

package/dist/decorators/system-action.decorator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @SystemAction() — tenant 없이 실행되어야 하는 시스템 작업 표시 데코레이터.
+ *
+ * 일반적으로 @RequireTenant()가 클래스 레벨에 붙어 있는 서비스라도,
+ * cron / 마이그레이션 / 모니터링 같은 메서드는 모든 tenant를 가로질러
+ * 동작해야 합니다. 그때 이 데코레이터로 "의도적으로 보호 제외"임을
+ * 명시하는 것이 안전합니다.
+ *
+ * 동작 전제:
+ *  forRoot.allowSystemActions: true 여야 실제로 작동.
+ *  (켜지 않으면 라이브러리가 보안 우회 가능성을 차단)
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 예시]
+ *
+ *   @Injectable()
+ *   @RequireTenant()
+ *   export class MaintenanceService {
+ *     // 일반 메서드 — tenant 컨텍스트 필요
+ *     async cleanupForCurrentTenant() { ... }
+ *
+ *     // 시스템 메서드 — tenant 컨텍스트 없이 실행 가능
+ *     @SystemAction()
+ *     async runDailyCleanupForAllTenants() {
+ *       const tenants = await tenantRegistry.findAll();
+ *       for (const t of tenants) {
+ *         await runWithTenant(t.id, async () => {
+ *           await this.cleanupForCurrentTenant();
+ *         });
+ *       }
+ *     }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare function SystemAction(): MethodDecorator;
+//# sourceMappingURL=system-action.decorator.d.ts.map

package/dist/decorators/system-action.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-action.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/system-action.decorator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,IAAI,eAAe,CAW9C"}

package/dist/decorators/system-action.decorator.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemAction = SystemAction;
+const constants_1 = require("../constants");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @SystemAction() — tenant 없이 실행되어야 하는 시스템 작업 표시 데코레이터.
+ *
+ * 일반적으로 @RequireTenant()가 클래스 레벨에 붙어 있는 서비스라도,
+ * cron / 마이그레이션 / 모니터링 같은 메서드는 모든 tenant를 가로질러
+ * 동작해야 합니다. 그때 이 데코레이터로 "의도적으로 보호 제외"임을
+ * 명시하는 것이 안전합니다.
+ *
+ * 동작 전제:
+ *  forRoot.allowSystemActions: true 여야 실제로 작동.
+ *  (켜지 않으면 라이브러리가 보안 우회 가능성을 차단)
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 예시]
+ *
+ *   @Injectable()
+ *   @RequireTenant()
+ *   export class MaintenanceService {
+ *     // 일반 메서드 — tenant 컨텍스트 필요
+ *     async cleanupForCurrentTenant() { ... }
+ *
+ *     // 시스템 메서드 — tenant 컨텍스트 없이 실행 가능
+ *     @SystemAction()
+ *     async runDailyCleanupForAllTenants() {
+ *       const tenants = await tenantRegistry.findAll();
+ *       for (const t of tenants) {
+ *         await runWithTenant(t.id, async () => {
+ *           await this.cleanupForCurrentTenant();
+ *         });
+ *       }
+ *     }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+function SystemAction() {
+    return function (_target, _propertyKey, descriptor) {
+        // 메서드 자체에 메타데이터 표식만 남깁니다.
+        // 실제 우회 로직은 @RequireTenant() 쪽에서 이 표식을 보고 처리.
+        Reflect.defineMetadata(constants_1.SYSTEM_ACTION_METADATA, true, descriptor.value);
+        return descriptor;
+    };
+}
+//# sourceMappingURL=system-action.decorator.js.map

package/dist/decorators/system-action.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-action.decorator.js","sourceRoot":"","sources":["../../src/decorators/system-action.decorator.ts"],"names":[],"mappings":";;AAuCA,oCAWC;AAlDD,4CAAsD;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,SAAgB,YAAY;IAC1B,OAAO,UACL,OAAY,EACZ,YAA6B,EAC7B,UAA8B;QAE9B,0BAA0B;QAC1B,8CAA8C;QAC9C,OAAO,CAAC,cAAc,CAAC,kCAAsB,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/tenant-context.decorator.d.ts

@@ -0,0 +1,33 @@
+import { TenantContextOptions } from '../interfaces/tenant-context-options.interface';
+/**
+ * ─────────────────────────────────────────────────────────────
+ * @TenantContext() — 백그라운드 큐 작업용 tenant 컨텍스트 복원 데코레이터.
+ *
+ * ⚠️ v0.2 정식 출시 예정. v0.1 스켈레톤만 존재.
+ *
+ * 동작:
+ *   BullMQ/Bull의 @Process 핸들러에 붙이면, job payload에서 tenant ID를
+ *   꺼내 AsyncLocalStorage.run()으로 컨텍스트를 만든 채 핸들러를 실행.
+ *
+ *   결과적으로 HTTP 요청과 동일한 보호망(@RequireTenant, Subscriber 등)이
+ *   백그라운드 작업에서도 그대로 동작합니다.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시]
+ *
+ *   @Processor('reports')
+ *   export class ReportProcessor {
+ *     @Process('monthly')
+ *     @TenantContext()                                 // job.data.tenantId 자동 추출
+ *     async generateMonthlyReport(job: Job) { ... }
+ *
+ *     @Process('quarterly')
+ *     @TenantContext({ extractFrom: j => j.data.orgId })  // 커스텀 추출
+ *     async generateQuarterly(job: Job) { ... }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare function TenantContext(options?: TenantContextOptions): MethodDecorator;
+//# sourceMappingURL=tenant-context.decorator.d.ts.map

package/dist/decorators/tenant-context.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/tenant-context.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gDAAgD,CAAC;AAGtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,eAAe,CAgCjF"}