nestjs-tenant-shield 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,28 @@
+"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 });
+/**
+ * 테스트 전용 헬퍼 배럴.
+ *
+ * 외부에서:
+ *   import { runWithTenant, expectCurrentTenant } from 'nestjs-tenant-shield/testing';
+ *
+ * 같은 형태로 가져다 쓸 수 있게 합니다.
+ *
+ * (subpath import 지원은 package.json "exports" 필드 설정 후 활성화 — v0.1.x 예정)
+ */
+__exportStar(require("./test-helpers"), exports);
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,iDAA+B"}

package/dist/testing/test-helpers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 라이브러리 사용자가 테스트 코드에서 쓰는 헬퍼 모음.
+ *
+ * 핵심 철학:
+ *   "다른 tenant의 데이터를 실수로 만지는 일을, 테스트 단계에서부터
+ *    절대 일어나지 않게 강제한다."
+ *
+ * runWithTenant / runWithoutTenant 는 이미 src/context/에 정의되어 있고
+ * 여기서는 그대로 재-export 합니다 (사용자 import 경로 통일).
+ *
+ * 추가로 테스트 전용 헬퍼:
+ *  - expectCurrentTenant   : 현재 컨텍스트의 tenant ID 단정
+ *  - clearTenantContext    : 테스트 간 컨텍스트 강제 초기화 (특수 케이스)
+ *  - mockTenantContext     : 동기적으로 컨텍스트만 깔아두기
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [기본 사용 패턴]
+ *
+ *   describe('StudentsService', () => {
+ *     it('A 학원 컨텍스트에서는 A 학생만 조회', async () => {
+ *       await runWithTenant('academy-A', async () => {
+ *         const students = await service.findAll();
+ *         expect(students.every(s => s.tenantId === 'academy-A')).toBe(true);
+ *       });
+ *     });
+ *
+ *     it('컨텍스트 없이 호출하면 throw', async () => {
+ *       await expect(service.findAll()).rejects.toThrow(MissingTenantContextError);
+ *     });
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export { resetGlobalOptions } from '../options/options.registry';
+export { resetGlobalCache } from '../cache/cache.registry';
+/**
+ * 현재 AsyncLocalStorage에 깔린 tenant ID가 예상과 같은지 단정.
+ *
+ * Jest assertion API와 호환되도록 throw 기반으로 작성.
+ * (expect(...).toBe 대신 직접 던지는 이유 — Jest matcher import 없이 동작)
+ */
+export declare function expectCurrentTenant(expected: string | null): void;
+/**
+ * 동기적으로 임시 tenant 컨텍스트를 깔고 콜백을 실행.
+ *
+ * 비동기 콜백을 쓸 수 없는 특수한 동기 헬퍼/유틸을 테스트할 때만 사용.
+ * 일반 케이스는 항상 runWithTenant(비동기 버전)를 우선 사용하세요.
+ */
+export declare function mockTenantContext<T>(tenantId: string, fn: () => T): T;
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/testing/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../src/testing/test-helpers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAQjE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErE"}

package/dist/testing/test-helpers.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetGlobalCache = exports.resetGlobalOptions = void 0;
+exports.expectCurrentTenant = expectCurrentTenant;
+exports.mockTenantContext = mockTenantContext;
+const tenant_context_storage_1 = require("../context/tenant-context.storage");
+/**
+ * ─────────────────────────────────────────────────────────────
+ * 라이브러리 사용자가 테스트 코드에서 쓰는 헬퍼 모음.
+ *
+ * 핵심 철학:
+ *   "다른 tenant의 데이터를 실수로 만지는 일을, 테스트 단계에서부터
+ *    절대 일어나지 않게 강제한다."
+ *
+ * runWithTenant / runWithoutTenant 는 이미 src/context/에 정의되어 있고
+ * 여기서는 그대로 재-export 합니다 (사용자 import 경로 통일).
+ *
+ * 추가로 테스트 전용 헬퍼:
+ *  - expectCurrentTenant   : 현재 컨텍스트의 tenant ID 단정
+ *  - clearTenantContext    : 테스트 간 컨텍스트 강제 초기화 (특수 케이스)
+ *  - mockTenantContext     : 동기적으로 컨텍스트만 깔아두기
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [기본 사용 패턴]
+ *
+ *   describe('StudentsService', () => {
+ *     it('A 학원 컨텍스트에서는 A 학생만 조회', async () => {
+ *       await runWithTenant('academy-A', async () => {
+ *         const students = await service.findAll();
+ *         expect(students.every(s => s.tenantId === 'academy-A')).toBe(true);
+ *       });
+ *     });
+ *
+ *     it('컨텍스트 없이 호출하면 throw', async () => {
+ *       await expect(service.findAll()).rejects.toThrow(MissingTenantContextError);
+ *     });
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+// runWithTenant / runWithoutTenant 는 'nestjs-tenant-shield'의 메인 진입점
+// (src/context를 통해 자동 export) 에서 그대로 가져다 쓰면 됩니다.
+// 여기서 또 export 하면 중복 export 충돌이 발생하므로 제외했습니다.
+// forRoot 없이 단위 테스트할 때 afterEach에서 전역 상태 리셋.
+var options_registry_1 = require("../options/options.registry");
+Object.defineProperty(exports, "resetGlobalOptions", { enumerable: true, get: function () { return options_registry_1.resetGlobalOptions; } });
+var cache_registry_1 = require("../cache/cache.registry");
+Object.defineProperty(exports, "resetGlobalCache", { enumerable: true, get: function () { return cache_registry_1.resetGlobalCache; } });
+/**
+ * 현재 AsyncLocalStorage에 깔린 tenant ID가 예상과 같은지 단정.
+ *
+ * Jest assertion API와 호환되도록 throw 기반으로 작성.
+ * (expect(...).toBe 대신 직접 던지는 이유 — Jest matcher import 없이 동작)
+ */
+function expectCurrentTenant(expected) {
+    const actual = tenant_context_storage_1.tenantContextStorage.getStore()?.tenantId ?? null;
+    if (actual !== expected) {
+        throw new Error(`expectCurrentTenant: expected "${expected}" but got "${actual}". ` +
+            '테스트 셋업의 runWithTenant 호출 위치를 확인하세요.');
+    }
+}
+/**
+ * 동기적으로 임시 tenant 컨텍스트를 깔고 콜백을 실행.
+ *
+ * 비동기 콜백을 쓸 수 없는 특수한 동기 헬퍼/유틸을 테스트할 때만 사용.
+ * 일반 케이스는 항상 runWithTenant(비동기 버전)를 우선 사용하세요.
+ */
+function mockTenantContext(tenantId, fn) {
+    return tenant_context_storage_1.tenantContextStorage.run({ tenantId, isSystemAction: false }, fn);
+}
+//# sourceMappingURL=test-helpers.js.map

package/dist/testing/test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../../src/testing/test-helpers.ts"],"names":[],"mappings":";;;AAoDA,kDAQC;AAQD,8CAEC;AAtED,8EAAyE;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,oEAAoE;AACpE,iDAAiD;AACjD,8CAA8C;AAE9C,6CAA6C;AAC7C,gEAAiE;AAAxD,sHAAA,kBAAkB,OAAA;AAC3B,0DAA2D;AAAlD,kHAAA,gBAAgB,OAAA;AAEzB;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,QAAuB;IACzD,MAAM,MAAM,GAAG,6CAAoB,CAAC,QAAQ,EAAE,EAAE,QAAQ,IAAI,IAAI,CAAC;IACjE,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,cAAc,MAAM,KAAK;YACjE,qCAAqC,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAI,QAAgB,EAAE,EAAW;IAChE,OAAO,6CAAoB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/typeorm/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TypeORM 통합 모듈.
+ *
+ * v0.1: TenantSubscriber + raw SQL 헬퍼
+ * v0.2: Prisma 어댑터 추가 예정 (별도 폴더)
+ * v0.3: Mongoose 어댑터
+ */
+export * from './tenant.subscriber';
+export * from './raw-sql.helper';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/typeorm/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/typeorm/index.js

@@ -0,0 +1,26 @@
+"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 });
+/**
+ * TypeORM 통합 모듈.
+ *
+ * v0.1: TenantSubscriber + raw SQL 헬퍼
+ * v0.2: Prisma 어댑터 추가 예정 (별도 폴더)
+ * v0.3: Mongoose 어댑터
+ */
+__exportStar(require("./tenant.subscriber"), exports);
+__exportStar(require("./raw-sql.helper"), exports);
+//# sourceMappingURL=index.js.map

package/dist/typeorm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/typeorm/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,sDAAoC;AACpC,mDAAiC"}

package/dist/typeorm/raw-sql.helper.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ─────────────────────────────────────────────────────────────
+ * withTenantWhere — Raw SQL 쿼리에 안전하게 tenant 조건을 부착하는 헬퍼.
+ *
+ * TenantSubscriber는 ORM(Repository, QueryBuilder)을 통한 호출만 보호합니다.
+ * 사용자가 어쩔 수 없이 repository.query()로 raw SQL을 직접 실행할 때는
+ * 라이브러리가 자동 주입을 해줄 수 없으므로, 이 헬퍼로 명시적으로 감싸세요.
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [사용 예시]
+ *
+ *   // 위험: tenant 조건이 빠져있음 (보호 X)
+ *   await repo.query('SELECT * FROM students');
+ *
+ *   // 권장: 헬퍼가 자동으로 WHERE 추가
+ *   const sql = withTenantWhere('SELECT * FROM students', 'tenant_id');
+ *   await repo.query(sql.text, sql.params);
+ *
+ * ─────────────────────────────────────────────────────────────
+ *
+ * [반환 구조]
+ *   {
+ *     text:   'SELECT * FROM students WHERE tenant_id = $1',
+ *     params: ['academy-A'],
+ *   }
+ *
+ * SQL injection 방지를 위해 반드시 parameterized query로 반환합니다.
+ */
+export interface WithTenantWhereResult {
+    text: string;
+    params: unknown[];
+}
+export declare function withTenantWhere(sql: string, tenantColumn: string, existingParams?: unknown[]): WithTenantWhereResult;
+//# sourceMappingURL=raw-sql.helper.d.ts.map

package/dist/typeorm/raw-sql.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-sql.helper.d.ts","sourceRoot":"","sources":["../../src/typeorm/raw-sql.helper.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAO,EAAO,GAC7B,qBAAqB,CAuBvB"}

package/dist/typeorm/raw-sql.helper.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTenantWhere = withTenantWhere;
+const get_current_tenant_id_1 = require("../context/get-current-tenant-id");
+const missing_tenant_context_error_1 = require("../errors/missing-tenant-context.error");
+function withTenantWhere(sql, tenantColumn, existingParams = []) {
+    const tenantId = (0, get_current_tenant_id_1.getCurrentTenantId)();
+    if (!tenantId) {
+        throw new missing_tenant_context_error_1.MissingTenantContextError('withTenantWhere: 현재 tenant 컨텍스트가 없습니다. raw SQL 사용 전 컨텍스트를 설정하세요.', 'raw-sql');
+    }
+    // SQL에 이미 WHERE가 있는지 단순 검사.
+    // (정확한 SQL 파서는 v0.2에서 도입 검토)
+    const hasWhere = /\bWHERE\b/i.test(sql);
+    const placeholder = `$${existingParams.length + 1}`;
+    const clause = `${tenantColumn} = ${placeholder}`;
+    const text = hasWhere
+        ? `${sql} AND ${clause}`
+        : `${sql} WHERE ${clause}`;
+    return {
+        text,
+        params: [...existingParams, tenantId],
+    };
+}
+//# sourceMappingURL=raw-sql.helper.js.map

package/dist/typeorm/raw-sql.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-sql.helper.js","sourceRoot":"","sources":["../../src/typeorm/raw-sql.helper.ts"],"names":[],"mappings":";;AAqCA,0CA2BC;AAhED,4EAAsE;AACtE,yFAAmF;AAoCnF,SAAgB,eAAe,CAC7B,GAAW,EACX,YAAoB,EACpB,iBAA4B,EAAE;IAE9B,MAAM,QAAQ,GAAG,IAAA,0CAAkB,GAAE,CAAC;IACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,wDAAyB,CACjC,kEAAkE,EAClE,SAAS,CACV,CAAC;IACJ,CAAC;IAED,4BAA4B;IAC5B,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IACpD,MAAM,MAAM,GAAG,GAAG,YAAY,MAAM,WAAW,EAAE,CAAC;IAElD,MAAM,IAAI,GAAG,QAAQ;QACnB,CAAC,CAAC,GAAG,GAAG,QAAQ,MAAM,EAAE;QACxB,CAAC,CAAC,GAAG,GAAG,UAAU,MAAM,EAAE,CAAC;IAE7B,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,CAAC,GAAG,cAAc,EAAE,QAAQ,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/typeorm/tenant.subscriber.d.ts

@@ -0,0 +1,61 @@
+import { EntitySubscriberInterface, InsertEvent, LoadEvent } from 'typeorm';
+import { TenantShieldOptions } from '../interfaces/tenant-shield-options.interface';
+/**
+ * ─────────────────────────────────────────────────────────────
+ * TenantSubscriber — v0.1의 가장 중요한 컴포넌트.
+ *
+ * TypeORM의 EventSubscriber는 모든 SELECT/INSERT/UPDATE/DELETE
+ * 동작에 끼어들 수 있는 hook입니다. 이 hook을 활용해서 사용자가
+ * 코드에서 WHERE를 빠뜨려도, 라이브러리가 자동으로 안전망을 깔아줍니다.
+ *
+ * 적용되는 보호 3가지:
+ *  1) beforeQuery (또는 QueryBuilder 가로채기): SELECT/UPDATE/DELETE에 자동 WHERE 주입
+ *  2) beforeInsert: INSERT 시 현재 tenant ID를 자동으로 컬럼에 주입
+ *  3) afterLoad: 어떤 escape hatch로든 다른 tenant의 entity가 반환되면 즉시 throw
+ *
+ * ⚠️ Raw SQL (repository.query()) 은 이 hook을 통과하지 않습니다.
+ *    이 경우 사용자가 withTenantWhere() 헬퍼로 수동 보호해야 합니다.
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare class TenantSubscriber implements EntitySubscriberInterface {
+    private readonly options;
+    constructor(options: TenantShieldOptions);
+    /**
+     * INSERT 직전 hook.
+     * tenant_id 컬럼이 비어 있으면 현재 컨텍스트의 tenantId를 자동으로 채워 넣습니다.
+     *
+     * 사용자가 "tenantId를 명시적으로 안 적어도 알아서 들어가는" 마법은 여기서 발생.
+     */
+    beforeInsert(event: InsertEvent<any>): void;
+    /**
+     * Entity가 DB에서 로드된 직후 hook.
+     *
+     * 어떤 경로로든 (raw SQL, escape hatch, 우회 코드) 다른 tenant의 데이터가
+     * 메모리에 올라왔다면 여기서 마지막으로 검출해 throw.
+     *
+     * "다층 방어"의 최종 안전망입니다.
+     */
+    afterLoad(entity: any, event?: LoadEvent<any>): void;
+    /**
+     * QueryBuilder의 SELECT/UPDATE/DELETE에 자동 WHERE 주입.
+     *
+     * TypeORM 0.3+에서는 beforeQuery 같은 hook이 제한적이라,
+     * 실제 구현은 EntityManager wrap 또는 QueryBuilder 가로채기를 통해 이뤄집니다.
+     *
+      * v0.1에서는 QueryBuilder 프로토타입을 monkey-patch하여
+      * getMany/getOne/getCount/execute 전에 자동 조건을 주입합니다.
+     */
+    /**
+     * 주어진 entity 클래스가 tenant 보호 대상인지 판정.
+     *
+     * 사용자가 forRoot에 entities를 명시했으면 그 화이트리스트로만 확인.
+     * 미명시 시 모든 entity를 검사 (기본 안전 모드).
+     */
+    private isTenantAwareEntity;
+}
+/**
+ * 모든 prototype 패치를 원복하고 모듈 상태를 초기화한다.
+ * e2e 테스트의 afterAll에서 호출해 테스트 간 오염을 방지한다.
+ */
+export declare function unpatch(): void;
+//# sourceMappingURL=tenant.subscriber.d.ts.map

package/dist/typeorm/tenant.subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.subscriber.d.ts","sourceRoot":"","sources":["../../src/typeorm/tenant.subscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,yBAAyB,EAEzB,WAAW,EACX,SAAS,EAIV,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AAIpF;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,gBAAiB,YAAW,yBAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,mBAAmB;IAOzD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI;IAwC3C;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI;IAwBpD;;;;;;;;OAQG;IAGH;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CAQ5B;AAiWD;;;GAGG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAoB9B"}