nestjs-tenant-shield 0.1.0

package/dist/cache/cache.registry.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setGlobalCache = setGlobalCache;
+exports.getGlobalCache = getGlobalCache;
+exports.resetGlobalCache = resetGlobalCache;
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 글로벌 캐시 registry — @Cacheable 데코레이터의 DI 우회로.
+ *
+ * 배경:
+ *   @Cacheable은 메서드 디스크립터를 직접 wrap 하기 때문에 NestJS DI
+ *   컨테이너에 접근할 수 없습니다. 그렇다고 사용자에게 매번 클래스에
+ *   `cacheService` 프로퍼티를 inject 하라고 강제하면 불편합니다.
+ *
+ *   해결: 모듈이 onApplicationBootstrap 시점에 캐시 인스턴스를 이 작은
+ *   글로벌 registry에 등록 → 데코레이터는 registry에서 가져옴.
+ *
+ *   사용자가 클래스 인스턴스에 `cacheService`를 명시적으로 두면 그게
+ *   우선 사용되고, 없으면 글로벌 fallback으로 동작합니다.
+ *
+ * ⚠️ 이 패턴의 한계:
+ *   - 한 프로세스에 하나의 캐시만 가능 (대부분 SaaS에서는 OK)
+ *   - 테스트 격리를 위해 reset이 필요 → resetGlobalCache 제공
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+let globalCache;
+/**
+ * 모듈 bootstrap 단계에서 1회 호출.
+ * 라이브러리 외부에서 직접 호출할 일은 없습니다.
+ */
+function setGlobalCache(cache) {
+    globalCache = cache;
+}
+/**
+ * @Cacheable 데코레이터가 fallback으로 사용하는 lookup 함수.
+ *
+ * 반환값:
+ *   - TenantAwareCacheService 인스턴스 (모듈 bootstrap 후 정상 상태)
+ *   - undefined (모듈이 아직 init되지 않았거나, 라이브러리 미사용 환경)
+ */
+function getGlobalCache() {
+    return globalCache;
+}
+/**
+ * 테스트 격리용. 각 테스트 케이스 후 호출해서 다음 테스트에 영향을 안 미치게.
+ */
+function resetGlobalCache() {
+    globalCache = undefined;
+}
+//# sourceMappingURL=cache.registry.js.map

package/dist/cache/cache.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.registry.js","sourceRoot":"","sources":["../../src/cache/cache.registry.ts"],"names":[],"mappings":";;AA8BA,wCAEC;AASD,wCAEC;AAKD,4CAEC;AAhDD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,IAAI,WAAgD,CAAC;AAErD;;;GAGG;AACH,SAAgB,cAAc,CAAC,KAA8B;IAC3D,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc;IAC5B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB;IAC9B,WAAW,GAAG,SAAS,CAAC;AAC1B,CAAC"}

package/dist/cache/cache.service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 캐시 백엔드 추상화.
+ *
+ * v0.1에서는 가장 단순한 in-memory Map 구현체를 기본 제공합니다.
+ * 프로덕션에서는 사용자가 Redis 등 외부 캐시로 교체할 수 있도록
+ * 인터페이스를 분리해 둡니다.
+ *
+ * 추후 nestjs-tenant-shield-redis 같은 어댑터 패키지로 분리 검토.
+ * ─────────────────────────────────────────────────────────────
+ */
+/**
+ * 모든 캐시 구현체가 충족해야 하는 계약.
+ */
+export interface TenantAwareCacheService {
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+}
+/**
+ * ─────────────────────────────────────────────────────────────
+ * In-Memory 캐시 구현체 (기본 제공).
+ *
+ * 단일 프로세스 + 개발/테스트 환경에 적합합니다.
+ * 멀티 인스턴스 배포(여러 컨테이너)에서는 캐시가 공유되지 않으므로
+ * Redis 어댑터로 교체 권장.
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare class InMemoryTenantAwareCacheService implements TenantAwareCacheService {
+    /**
+     * 캐시 본체.
+     * value 옆에 expiresAt(ms epoch)을 저장해 lazy expiration 처리.
+     */
+    private readonly store;
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    /**
+     * 테스트나 tenant 데이터 삭제(GDPR purge) 시 활용.
+     * 특정 prefix(예: 'academy-A:')로 시작하는 모든 캐시 키 제거.
+     */
+    deleteByPrefix(prefix: string): Promise<void>;
+}
+//# sourceMappingURL=cache.service.d.ts.map

package/dist/cache/cache.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.service.d.ts","sourceRoot":"","sources":["../../src/cache/cache.service.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBACa,+BAAgC,YAAW,uBAAuB;IAC7E;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4D;IAE5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAY9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC;;;OAGG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpD"}

package/dist/cache/cache.service.js

@@ -0,0 +1,64 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryTenantAwareCacheService = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * In-Memory 캐시 구현체 (기본 제공).
+ *
+ * 단일 프로세스 + 개발/테스트 환경에 적합합니다.
+ * 멀티 인스턴스 배포(여러 컨테이너)에서는 캐시가 공유되지 않으므로
+ * Redis 어댑터로 교체 권장.
+ * ─────────────────────────────────────────────────────────────
+ */
+let InMemoryTenantAwareCacheService = class InMemoryTenantAwareCacheService {
+    constructor() {
+        /**
+         * 캐시 본체.
+         * value 옆에 expiresAt(ms epoch)을 저장해 lazy expiration 처리.
+         */
+        this.store = new Map();
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        // TTL 만료 검사. 만료됐으면 삭제 후 미스로 처리.
+        if (entry.expiresAt < Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlSeconds) {
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + ttlSeconds * 1000,
+        });
+    }
+    async del(key) {
+        this.store.delete(key);
+    }
+    /**
+     * 테스트나 tenant 데이터 삭제(GDPR purge) 시 활용.
+     * 특정 prefix(예: 'academy-A:')로 시작하는 모든 캐시 키 제거.
+     */
+    async deleteByPrefix(prefix) {
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix)) {
+                this.store.delete(key);
+            }
+        }
+    }
+};
+exports.InMemoryTenantAwareCacheService = InMemoryTenantAwareCacheService;
+exports.InMemoryTenantAwareCacheService = InMemoryTenantAwareCacheService = __decorate([
+    (0, common_1.Injectable)()
+], InMemoryTenantAwareCacheService);
+//# sourceMappingURL=cache.service.js.map

package/dist/cache/cache.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.service.js","sourceRoot":"","sources":["../../src/cache/cache.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAuB5C;;;;;;;;GAQG;AAEI,IAAM,+BAA+B,GAArC,MAAM,+BAA+B;IAArC;QACL;;;WAGG;QACc,UAAK,GAAG,IAAI,GAAG,EAAiD,CAAC;IAoCpF,CAAC;IAlCC,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,gCAAgC;QAChC,IAAI,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,UAAkB;QACvD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI;SAC1C,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,cAAc,CAAC,MAAc;QACjC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAA;AAzCY,0EAA+B;0CAA/B,+BAA+B;IAD3C,IAAA,mBAAU,GAAE;GACA,+BAA+B,CAyC3C"}

package/dist/cache/index.d.ts

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

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

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

package/dist/cache/index.js

@@ -0,0 +1,19 @@
+"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("./cache.service"), exports);
+__exportStar(require("./cache.registry"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

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

package/dist/constants/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 라이브러리 전역에서 공유하는 상수 모음.
+ *
+ * 두 종류가 들어 있습니다:
+ *
+ *  1) DI 토큰         — NestJS 의존성 주입 시 옵션 객체를 식별하는 키.
+ *  2) 메타데이터 키   — reflect-metadata로 메서드/클래스에 표식을 남길 때
+ *                       사용하는 문자열 키. 다른 곳에서 같은 키를 쓰면 충돌이
+ *                       나므로 라이브러리 prefix를 붙여 고유성을 확보합니다.
+ *
+ * 모든 키는 'nestjs-tenant-shield:' prefix를 사용 — 외부와 충돌 방지.
+ * ─────────────────────────────────────────────────────────────
+ */
+/**
+ * forRoot()에서 받은 옵션 객체(TenantShieldOptions)를 DI 컨테이너에
+ * 등록할 때 사용하는 토큰.
+ *
+ * 미들웨어/Subscriber 등이 `@Inject(TENANT_SHIELD_OPTIONS)`로
+ * 같은 인스턴스를 받아 옵니다.
+ */
+export declare const TENANT_SHIELD_OPTIONS: unique symbol;
+/**
+ * 캐시 서비스(TenantAwareCacheService 구현체)를 DI에 등록할 때 쓰는 토큰.
+ *
+ * 기본값은 InMemoryTenantAwareCacheService(모듈에서 자동 등록).
+ * 사용자가 Redis 등으로 교체하려면:
+ *
+ *   @Module({
+ *     providers: [
+ *       { provide: TENANT_SHIELD_CACHE, useClass: RedisCacheAdapter },
+ *     ],
+ *   })
+ */
+export declare const TENANT_SHIELD_CACHE: unique symbol;
+/**
+ * @RequireTenant()가 메서드에 남기는 메타데이터 키.
+ * Subscriber 또는 디버깅 도구가 "이 메서드가 보호 대상인지" 확인할 때 사용.
+ *
+ * 값은 RequireTenantOptions 객체.
+ */
+export declare const REQUIRE_TENANT_METADATA = "nestjs-tenant-shield:require-tenant";
+/**
+ * @SystemAction()이 메서드에 남기는 메타데이터 키.
+ * @RequireTenant()의 클래스 레벨 적용 시 이 표식이 있는 메서드는
+ * 자동 wrapping에서 건너뜁니다.
+ *
+ * 값은 boolean (true).
+ */
+export declare const SYSTEM_ACTION_METADATA = "nestjs-tenant-shield:system-action";
+/**
+ * @Cacheable()이 메서드에 남기는 메타데이터 키.
+ * (현재는 데코레이터가 디스크립터를 직접 감싸므로 동작에는 필수 아님.
+ *  향후 introspection / 디버깅 / 캐시 무효화 도구에서 사용 예정.)
+ */
+export declare const CACHEABLE_METADATA = "nestjs-tenant-shield:cacheable";
+/**
+ * 캐시 키의 tenant prefix 구분자.
+ * 'academy-A' + ':' + 'StudentsService.findAll' 처럼 조합.
+ *
+ * 변경 시 캐시 호환성이 깨지므로 메이저 버전 업데이트에서만 변경.
+ */
+export declare const CACHE_KEY_DELIMITER = ":";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,eAAyC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,eAAuC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,wCAAwC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,uCAAuC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,mCAAmC,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/constants/index.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 라이브러리 전역에서 공유하는 상수 모음.
+ *
+ * 두 종류가 들어 있습니다:
+ *
+ *  1) DI 토큰         — NestJS 의존성 주입 시 옵션 객체를 식별하는 키.
+ *  2) 메타데이터 키   — reflect-metadata로 메서드/클래스에 표식을 남길 때
+ *                       사용하는 문자열 키. 다른 곳에서 같은 키를 쓰면 충돌이
+ *                       나므로 라이브러리 prefix를 붙여 고유성을 확보합니다.
+ *
+ * 모든 키는 'nestjs-tenant-shield:' prefix를 사용 — 외부와 충돌 방지.
+ * ─────────────────────────────────────────────────────────────
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_KEY_DELIMITER = exports.CACHEABLE_METADATA = exports.SYSTEM_ACTION_METADATA = exports.REQUIRE_TENANT_METADATA = exports.TENANT_SHIELD_CACHE = exports.TENANT_SHIELD_OPTIONS = void 0;
+/**
+ * forRoot()에서 받은 옵션 객체(TenantShieldOptions)를 DI 컨테이너에
+ * 등록할 때 사용하는 토큰.
+ *
+ * 미들웨어/Subscriber 등이 `@Inject(TENANT_SHIELD_OPTIONS)`로
+ * 같은 인스턴스를 받아 옵니다.
+ */
+exports.TENANT_SHIELD_OPTIONS = Symbol('nestjs-tenant-shield:options');
+/**
+ * 캐시 서비스(TenantAwareCacheService 구현체)를 DI에 등록할 때 쓰는 토큰.
+ *
+ * 기본값은 InMemoryTenantAwareCacheService(모듈에서 자동 등록).
+ * 사용자가 Redis 등으로 교체하려면:
+ *
+ *   @Module({
+ *     providers: [
+ *       { provide: TENANT_SHIELD_CACHE, useClass: RedisCacheAdapter },
+ *     ],
+ *   })
+ */
+exports.TENANT_SHIELD_CACHE = Symbol('nestjs-tenant-shield:cache');
+/**
+ * @RequireTenant()가 메서드에 남기는 메타데이터 키.
+ * Subscriber 또는 디버깅 도구가 "이 메서드가 보호 대상인지" 확인할 때 사용.
+ *
+ * 값은 RequireTenantOptions 객체.
+ */
+exports.REQUIRE_TENANT_METADATA = 'nestjs-tenant-shield:require-tenant';
+/**
+ * @SystemAction()이 메서드에 남기는 메타데이터 키.
+ * @RequireTenant()의 클래스 레벨 적용 시 이 표식이 있는 메서드는
+ * 자동 wrapping에서 건너뜁니다.
+ *
+ * 값은 boolean (true).
+ */
+exports.SYSTEM_ACTION_METADATA = 'nestjs-tenant-shield:system-action';
+/**
+ * @Cacheable()이 메서드에 남기는 메타데이터 키.
+ * (현재는 데코레이터가 디스크립터를 직접 감싸므로 동작에는 필수 아님.
+ *  향후 introspection / 디버깅 / 캐시 무효화 도구에서 사용 예정.)
+ */
+exports.CACHEABLE_METADATA = 'nestjs-tenant-shield:cacheable';
+/**
+ * 캐시 키의 tenant prefix 구분자.
+ * 'academy-A' + ':' + 'StudentsService.findAll' 처럼 조합.
+ *
+ * 변경 시 캐시 호환성이 깨지므로 메이저 버전 업데이트에서만 변경.
+ */
+exports.CACHE_KEY_DELIMITER = ':';
+//# sourceMappingURL=index.js.map

package/dist/constants/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH;;;;;;GAMG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,8BAA8B,CAAC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,4BAA4B,CAAC,CAAC;AAExE;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG,qCAAqC,CAAC;AAE7E;;;;;;GAMG;AACU,QAAA,sBAAsB,GAAG,oCAAoC,CAAC;AAE3E;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,gCAAgC,CAAC;AAEnE;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG,GAAG,CAAC"}

package/dist/context/get-current-tenant-id.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 현재 요청의 tenant ID를 조회합니다.
+ *
+ * 비즈니스 로직 안에서 "지금 누구의 데이터를 다루고 있는지" 알고 싶을 때 사용.
+ *
+ * 반환값:
+ *  - string : 컨텍스트가 정상 설정된 경우 tenant ID
+ *  - null   : 컨텍스트가 없거나 시스템 작업인 경우
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 예시]
+ *
+ *   @Injectable()
+ *   export class AuditService {
+ *     async log(action: string) {
+ *       const tenantId = getCurrentTenantId();
+ *       await this.repo.save({ action, tenantId, occurredAt: new Date() });
+ *     }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [주의]
+ *  이 함수는 절대 throw하지 않습니다. tenant가 없으면 그냥 null을 반환합니다.
+ *  "없으면 거부"하는 보호 로직은 @RequireTenant() 데코레이터의 역할입니다.
+ *  → 일반 비즈니스 코드에서 throw 책임이 분산되면 추적이 어려워지기 때문.
+ */
+export declare function getCurrentTenantId(): string | null;
+//# sourceMappingURL=get-current-tenant-id.d.ts.map

package/dist/context/get-current-tenant-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-current-tenant-id.d.ts","sourceRoot":"","sources":["../../src/context/get-current-tenant-id.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAOlD"}

package/dist/context/get-current-tenant-id.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentTenantId = getCurrentTenantId;
+const tenant_context_storage_1 = require("./tenant-context.storage");
+/**
+ * 현재 요청의 tenant ID를 조회합니다.
+ *
+ * 비즈니스 로직 안에서 "지금 누구의 데이터를 다루고 있는지" 알고 싶을 때 사용.
+ *
+ * 반환값:
+ *  - string : 컨텍스트가 정상 설정된 경우 tenant ID
+ *  - null   : 컨텍스트가 없거나 시스템 작업인 경우
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 예시]
+ *
+ *   @Injectable()
+ *   export class AuditService {
+ *     async log(action: string) {
+ *       const tenantId = getCurrentTenantId();
+ *       await this.repo.save({ action, tenantId, occurredAt: new Date() });
+ *     }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [주의]
+ *  이 함수는 절대 throw하지 않습니다. tenant가 없으면 그냥 null을 반환합니다.
+ *  "없으면 거부"하는 보호 로직은 @RequireTenant() 데코레이터의 역할입니다.
+ *  → 일반 비즈니스 코드에서 throw 책임이 분산되면 추적이 어려워지기 때문.
+ */
+function getCurrentTenantId() {
+    // AsyncLocalStorage에서 현재 비동기 컨텍스트에 묶인 store를 가져옵니다.
+    // store가 undefined면 한 번도 storage.run()으로 감싸지지 않은 코드.
+    const store = tenant_context_storage_1.tenantContextStorage.getStore();
+    // 옵셔널 체이닝(?.)으로 안전하게 접근. 없으면 자연스럽게 null.
+    return store?.tenantId ?? null;
+}
+//# sourceMappingURL=get-current-tenant-id.js.map

package/dist/context/get-current-tenant-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-current-tenant-id.js","sourceRoot":"","sources":["../../src/context/get-current-tenant-id.ts"],"names":[],"mappings":";;AA8BA,gDAOC;AArCD,qEAAgE;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,kBAAkB;IAChC,oDAAoD;IACpD,qDAAqD;IACrD,MAAM,KAAK,GAAG,6CAAoB,CAAC,QAAQ,EAAE,CAAC;IAE9C,yCAAyC;IACzC,OAAO,KAAK,EAAE,QAAQ,IAAI,IAAI,CAAC;AACjC,CAAC"}

package/dist/context/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 컨텍스트 관련 public API 배럴 export.
+ */
+export * from './tenant-context.storage';
+export * from './get-current-tenant-id';
+export * from './run-with-tenant';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,23 @@
+"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 });
+/**
+ * 컨텍스트 관련 public API 배럴 export.
+ */
+__exportStar(require("./tenant-context.storage"), exports);
+__exportStar(require("./get-current-tenant-id"), exports);
+__exportStar(require("./run-with-tenant"), exports);
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;GAEG;AACH,2DAAyC;AACzC,0DAAwC;AACxC,oDAAkC"}

package/dist/context/run-with-tenant.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 명시적으로 tenant 컨텍스트를 설정한 채 비동기 함수를 실행합니다.
+ *
+ * 주 용도:
+ *  1) 테스트: 매 테스트 케이스마다 어떤 tenant인지 명시
+ *  2) 시스템 작업: 모든 tenant를 순회하는 cron 등
+ *  3) 마이그레이션 스크립트: 특정 tenant에 대해 직접 작업
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시 1 — 테스트]
+ *
+ *   await runWithTenant('academy-A', async () => {
+ *     const students = await service.findAll();
+ *     expect(students.every(s => s.tenantId === 'academy-A')).toBe(true);
+ *   });
+ *
+ * [예시 2 — 모든 tenant 순회]
+ *
+ *   for (const t of await tenantRegistry.findAll()) {
+ *     await runWithTenant(t.id, async () => {
+ *       await this.dailyCleanupService.run();
+ *     });
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare function runWithTenant<T>(tenantId: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * tenant 없이 시스템 작업을 실행합니다.
+ *
+ * forRoot.allowSystemActions가 true여야 의미가 있습니다.
+ * 컨텍스트에 isSystemAction: true 플래그를 박아 두어
+ * Subscriber/데코레이터가 "이건 의도된 무-tenant 실행"임을 알 수 있게 함.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * 🚨 보안 경고
+ *
+ *   이 함수는 라이브러리의 모든 자동 격리 보호를 의도적으로 해제합니다.
+ *   잘못 쓰면 단 한 번의 호출로 전 tenant 데이터가 한 결과 셋에 섞여 나올 수
+ *   있고, 그 결과가 사용자에게 노출되면 회사가 멈춥니다.
+ *
+ *   ✅ 쓰는 게 정당한 경우
+ *     - 시스템 테이블(tenant_id 컬럼이 없는 메타 테이블) 접근
+ *     - "모든 tenant 한 번에 집계"가 진짜 비즈니스 요구인 운영 통계
+ *     - 마이그레이션/데이터 보정 스크립트 (운영자 직접 실행)
+ *
+ *   ❌ 절대 쓰면 안 되는 경우
+ *     - HTTP 요청 핸들러 (사용자 요청 안에서 호출되면 그 사용자에게 다른
+ *       tenant 데이터가 흘러갈 가능성이 즉시 생김)
+ *     - "테스트가 빨리 지나가게 하려고" 임시 우회
+ *     - tenant ID 추출이 귀찮아서 우회 — 99%는 runWithTenant 루프가 정답
+ *
+ *   📋 운영 권장 사항
+ *     - 호출 위치마다 보안 로그를 남길 것 (누가/언제/왜 실행했는지)
+ *     - 가능하면 runWithTenant(t.id, ...) 루프로 대체할 수 있는지 먼저 검토
+ *     - 코드 리뷰에서 이 함수 호출은 반드시 검토 대상으로 표시
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [올바른 예시 — 시스템 테이블 접근]
+ *
+ *   await runWithoutTenant(async () => {
+ *     // tenant_id 컬럼이 없는 메타 테이블. 정당한 무-tenant 접근.
+ *     return this.featureFlagsService.loadAll();
+ *   });
+ *
+ * [잘못된 패턴 — 게으른 우회]
+ *
+ *   // ❌ 이렇게 쓰지 마세요.
+ *   await runWithoutTenant(async () => {
+ *     return this.studentsService.findAll(); // 전 학원 학생 다 나옴
+ *   });
+ *
+ *   // ✅ 올바른 패턴 — 명시적 tenant 루프
+ *   for (const t of await tenantRegistry.findAll()) {
+ *     await runWithTenant(t.id, () => this.studentsService.cleanup());
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare function runWithoutTenant<T>(fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=run-with-tenant.d.ts.map

package/dist/context/run-with-tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-tenant.d.ts","sourceRoot":"","sources":["../../src/context/run-with-tenant.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpE"}

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

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithTenant = runWithTenant;
+exports.runWithoutTenant = runWithoutTenant;
+const tenant_context_storage_1 = require("./tenant-context.storage");
+/**
+ * 명시적으로 tenant 컨텍스트를 설정한 채 비동기 함수를 실행합니다.
+ *
+ * 주 용도:
+ *  1) 테스트: 매 테스트 케이스마다 어떤 tenant인지 명시
+ *  2) 시스템 작업: 모든 tenant를 순회하는 cron 등
+ *  3) 마이그레이션 스크립트: 특정 tenant에 대해 직접 작업
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [예시 1 — 테스트]
+ *
+ *   await runWithTenant('academy-A', async () => {
+ *     const students = await service.findAll();
+ *     expect(students.every(s => s.tenantId === 'academy-A')).toBe(true);
+ *   });
+ *
+ * [예시 2 — 모든 tenant 순회]
+ *
+ *   for (const t of await tenantRegistry.findAll()) {
+ *     await runWithTenant(t.id, async () => {
+ *       await this.dailyCleanupService.run();
+ *     });
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+function runWithTenant(tenantId, fn) {
+    // storage.run()의 첫 번째 인자가 이 비동기 흐름의 store가 됩니다.
+    // 콜백 안에서 호출되는 모든 await/Promise 체인은 같은 store를 공유.
+    return tenant_context_storage_1.tenantContextStorage.run({ tenantId, isSystemAction: false }, fn);
+}
+/**
+ * tenant 없이 시스템 작업을 실행합니다.
+ *
+ * forRoot.allowSystemActions가 true여야 의미가 있습니다.
+ * 컨텍스트에 isSystemAction: true 플래그를 박아 두어
+ * Subscriber/데코레이터가 "이건 의도된 무-tenant 실행"임을 알 수 있게 함.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * 🚨 보안 경고
+ *
+ *   이 함수는 라이브러리의 모든 자동 격리 보호를 의도적으로 해제합니다.
+ *   잘못 쓰면 단 한 번의 호출로 전 tenant 데이터가 한 결과 셋에 섞여 나올 수
+ *   있고, 그 결과가 사용자에게 노출되면 회사가 멈춥니다.
+ *
+ *   ✅ 쓰는 게 정당한 경우
+ *     - 시스템 테이블(tenant_id 컬럼이 없는 메타 테이블) 접근
+ *     - "모든 tenant 한 번에 집계"가 진짜 비즈니스 요구인 운영 통계
+ *     - 마이그레이션/데이터 보정 스크립트 (운영자 직접 실행)
+ *
+ *   ❌ 절대 쓰면 안 되는 경우
+ *     - HTTP 요청 핸들러 (사용자 요청 안에서 호출되면 그 사용자에게 다른
+ *       tenant 데이터가 흘러갈 가능성이 즉시 생김)
+ *     - "테스트가 빨리 지나가게 하려고" 임시 우회
+ *     - tenant ID 추출이 귀찮아서 우회 — 99%는 runWithTenant 루프가 정답
+ *
+ *   📋 운영 권장 사항
+ *     - 호출 위치마다 보안 로그를 남길 것 (누가/언제/왜 실행했는지)
+ *     - 가능하면 runWithTenant(t.id, ...) 루프로 대체할 수 있는지 먼저 검토
+ *     - 코드 리뷰에서 이 함수 호출은 반드시 검토 대상으로 표시
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [올바른 예시 — 시스템 테이블 접근]
+ *
+ *   await runWithoutTenant(async () => {
+ *     // tenant_id 컬럼이 없는 메타 테이블. 정당한 무-tenant 접근.
+ *     return this.featureFlagsService.loadAll();
+ *   });
+ *
+ * [잘못된 패턴 — 게으른 우회]
+ *
+ *   // ❌ 이렇게 쓰지 마세요.
+ *   await runWithoutTenant(async () => {
+ *     return this.studentsService.findAll(); // 전 학원 학생 다 나옴
+ *   });
+ *
+ *   // ✅ 올바른 패턴 — 명시적 tenant 루프
+ *   for (const t of await tenantRegistry.findAll()) {
+ *     await runWithTenant(t.id, () => this.studentsService.cleanup());
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+function runWithoutTenant(fn) {
+    return tenant_context_storage_1.tenantContextStorage.run({ tenantId: null, isSystemAction: true }, fn);
+}
+//# sourceMappingURL=run-with-tenant.js.map