@xfilecom/core-sdk 1.3.23

package/README.md

@@ -0,0 +1,664 @@
+# @xfilecom/core-sdk
+
+NestJS 마이크로서비스용 Core SDK — DB, 인증, 로깅, 공통 응답, 설정 로드, 해시 검증 등을 하나의 패키지로 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [설정 파일 위치 (표준)](#설정-파일-위치-표준)
+- [설정 소스 (.env vs YAML)](#설정-소스-env-vs-yaml)
+- [사용 범위 요약](#사용-범위-요약)
+- [CoreModule](#coremodule)
+- [설정 파일 (application.yml)](#설정-파일-applicationyml)
+- [설정 루트·Config 로더](#설정-루트config-로더)
+- [Crypto (비밀번호·조회용 해시)](#crypto-비밀번호조회용-해시)
+- [Hash verification](#hash-verification)
+- [기능 옵션](#기능-옵션)
+- [Database](#database)
+- [Controller / Service 예시](#controller--service-예시)
+- [Guards · Decorators · Interceptors · Filters](#guards--decorators--interceptors--filters)
+- [기타 유틸](#기타-유틸)
+- [Database 연결 실패 시](#database-연결-실패-시)
+- [수정 사항](#수정-사항)
+- [라이선스](#라이선스)
+
+---
+
+## 설치
+
+```bash
+npm install @xfilecom/core-sdk
+```
+
+---
+
+## 설정 파일 위치 (표준)
+
+다른 서비스/팀과 동일한 방식으로 사용하려면 **설정 파일 위치를 아래 규칙으로 통일**합니다.
+
+| 항목 | 규칙 |
+|------|------|
+| **파일 경로** | `{프로젝트 루트}/application.yml` 또는 `application.yaml` |
+| **프로젝트 루트** | 기본값 `process.cwd()`. 필요 시 `loadApplicationYaml({ rootDir })` 로 지정 |
+| **파일명 우선순위** | `application.yml` → `application.yaml` (먼저 찾은 것 사용) |
+| **환경별 병합** | 같은 루트에 `application-{env}.yml` (예: `application-development.yml`) 있으면 base 위에 deep merge |
+
+코드에서 루트만 맞추면 항상 같은 위치에서 설정을 읽습니다.
+
+```typescript
+import { loadApplicationYaml, DEFAULT_CONFIG_FILENAMES } from '@xfilecom/core-sdk';
+
+// 기본: process.cwd() 에서 application.yml / application.yaml 탐색
+const config = await loadApplicationYaml();
+
+// 루트 지정 (예: 패키지 루트)
+const config = await loadApplicationYaml({ rootDir: path.join(__dirname, '..') });
+
+// 환경별 설정 병합
+const config = await loadApplicationYaml({ env: process.env.NODE_ENV });
+```
+
+- 파일이 없으면 예외 없이 빈 객체 `{}` 반환.
+- 상수: `DEFAULT_CONFIG_FILENAMES`, `ENV_CONFIG_FILENAME_PATTERN` (index에서 export).
+
+---
+
+## 설정 소스 (.env vs YAML)
+
+**YAML을 쓸지, 환경 변수(.env)만 쓸지, 또는 둘 다 쓸지**를 설정할 수 있습니다.
+
+### 옵션 (configSource)
+
+| 값 | 동작 |
+|----|------|
+| `yaml` | `application.yml`만 읽음 (기본값) |
+| `env` | YAML을 읽지 않고, `process.env`(DB_*, JWT_*, HASH_* 등)로 config 객체 생성 |
+| `yamlWithEnvOverrides` | YAML 로드 후, 같은 키가 환경 변수에 있으면 그 값으로 덮어씀 |
+
+### 어디에 설정하나요?
+
+**1) 코드에서 지정 (권장)**
+
+`loadApplicationYaml()` 호출 시 옵션으로 넘깁니다.
+
+```typescript
+import { loadApplicationYaml, type ConfigSource } from '@xfilecom/core-sdk';
+
+// YAML만 사용 (기본)
+const config = await loadApplicationYaml();
+
+// .env(환경 변수)만 사용 — application.yml 없이 DB_*, JWT_* 등으로 config 구성
+const config = await loadApplicationYaml({ configSource: 'env' });
+
+// YAML 먼저 로드하고, 환경 변수로 덮어쓰기
+const config = await loadApplicationYaml({ configSource: 'yamlWithEnvOverrides', env: process.env.NODE_ENV });
+```
+
+**2) 환경 변수로 지정**
+
+코드는 그대로 두고, **실행 환경 또는 .env 파일**에 다음 키로 소스를 정합니다.
+
+| 설정 위치 | 예시 |
+|-----------|------|
+| **.env 파일** | `CONFIG_SOURCE=env` 또는 `CONFIG_SOURCE=yamlWithEnvOverrides` |
+| **쉘/실행 시** | `CONFIG_SOURCE=env node dist/main.js` |
+
+- `CONFIG_SOURCE` 가 없으면 기본값 `yaml` 로 동작합니다.
+- 상수 이름: `CONFIG_SOURCE_ENV_KEY` (`'CONFIG_SOURCE'`) — index에서 export.
+
+```bash
+# .env
+CONFIG_SOURCE=env
+DB_HOST=localhost
+JWT_SECRET=my-secret
+```
+
+이렇게 하면 `loadApplicationYaml()` 호출 시 옵션에 `configSource`를 안 넘겨도, `process.env.CONFIG_SOURCE`를 읽어서 동일하게 동작합니다. (앱에서 dotenv 등으로 .env를 먼저 로드해야 함)
+
+### configSource: 'env' 일 때 매핑
+
+환경 변수만 쓸 때 아래 키들이 config 객체로 매핑됩니다.
+
+- **database**: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`(또는 `DB_DATABASE`), `DB_SSL`, `DB_CONNECTION_LIMIT`
+- **jwt**: `JWT_SECRET`, `JWT_EXPIRES_IN`
+- **hashVerification.default**: `HASH_VERIFICATION_SECRET`
+- **hashVerification.profiles.email**: `EMAIL_HASH_SECRET` (없으면 `HASH_VERIFICATION_SECRET`)
+
+---
+
+## 사용 범위 요약
+
+| 구분 | 내용 |
+|------|------|
+| **모듈** | `CoreModule.forRoot()`, `forMicroservice()`, `forHttpApi()`, `forHybrid()` |
+| **설정** | `loadApplicationYaml()` / `loadApplicationYamlSync()` — 표준 경로 `application.yml` 또는 `configSource: 'env'` 로 환경 변수만 사용 |
+| **설정 루트·로더** | `resolveConfigRootDir()` (모노레포 등 설정 디렉터리 탐색), `createConfigLoader()` (한 번 로드 + 캐시 + getFullConfig / getServiceConfig) |
+| **Crypto** | `pbkdf2HashPassword` / `pbkdf2VerifyPassword` (saltHex:hashHex), `lookupHash` / `compareLookupHash` (키 파생 옵션), `deriveKeySha256` |
+| **해시/검증** | `hashValue`, `compareValue`, `hashByKey`, `compareByKey`, `hashEmail`, `compareEmail`, `lookupHash`, `compareLookupHash` (YAML `hashVerification` + `keyDerivation` 연동) |
+| **DB** | Drizzle ORM + MySQL, `DatabaseQuery`, `ServiceHelpers` (getDb, withTransaction, createPaginationResult 등) |
+| **컨트롤러** | `ControllerHelpers` (parsePagination, parseSort, parseFilters, success, error) |
+| **인증** | `JwtAuthGuard`, `RolesGuard`, `AuthHelpers`, `@Public()`, `@User()`, `@Roles()` |
+| **인터셉터** | Logging, ErrorHandling, ResponseTransform, DatabaseCheck |
+| **필터** | `AllExceptionsFilter` |
+| **기타** | `ErrorUtils`, `LoggerHelpers`, `ConfigValidator`, `getLoggingConfigFromEnv` |
+
+---
+
+## CoreModule
+
+### 마이크로서비스
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CoreModule } from '@xfilecom/core-sdk';
+
+@Module({
+  imports: [CoreModule.forMicroservice()],
+})
+export class AppModule {}
+```
+
+### HTTP API
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CoreModule } from '@xfilecom/core-sdk';
+import { schema } from './database/schema';
+
+@Module({
+  imports: [
+    CoreModule.forHttpApi({
+      database: { schema },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 하이브리드 (HTTP + TCP)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CoreModule } from '@xfilecom/core-sdk';
+
+@Module({
+  imports: [CoreModule.forHybrid()],
+})
+export class AppModule {}
+```
+
+### 커스텀 설정 (forRoot)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CoreModule } from '@xfilecom/core-sdk';
+import { mySchema } from './database/schema';
+
+@Module({
+  imports: [
+    CoreModule.forRoot({
+      database: { schema: mySchema },
+      jwt: { secret: process.env.JWT_SECRET, expiresIn: '7d' },
+      response: { commonResponse: true },
+      interceptors: { logging: true, databaseCheck: true },
+      guards: { jwt: true },
+      filters: { exception: true },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## 설정 파일 (application.yml)
+
+- **위치**: [설정 파일 위치 (표준)](#설정-파일-위치-표준) 참고.
+- **소스 선택**: [설정 소스 (.env vs YAML)](#설정-소스-env-vs-yaml) 참고 — `configSource` 또는 `CONFIG_SOURCE` 로 YAML / .env 선택 가능.
+- **비동기**: `loadApplicationYaml(options?)`
+- **동기**: `loadApplicationYamlSync(options?)` (bootstrap 전 등)
+- **syncEnvKeys**: YAML 로드 후 config 일부를 `process.env`에 채울 수 있음. ConfigValidator / JwtAuthGuard 등이 env를 참조할 때 YAML만 써도 연동 가능.
+
+```typescript
+import { loadApplicationYaml, loadApplicationYamlSync } from '@xfilecom/core-sdk';
+
+const config = await loadApplicationYaml();
+const dbHost = config?.database?.host ?? process.env.DB_HOST;
+
+const configWithEnv = await loadApplicationYaml({ env: process.env.NODE_ENV });
+const configSync = loadApplicationYamlSync({ rootDir: path.join(__dirname, '..') });
+
+// YAML 로드 후 JWT 등을 process.env에 동기화 (Guard/ConfigValidator와 연동)
+const config = await loadApplicationYaml({
+  env: process.env.NODE_ENV,
+  syncEnvKeys: {
+    JWT_SECRET: 'jwt.secret',
+    JWT_EXPIRES_IN: 'jwt.expiresIn',
+    HASH_VERIFICATION_SECRET: 'hashVerification.default.secret',
+  },
+});
+```
+
+설정 파일 안에는 DB, JWT, `hashVerification` 등 자유롭게 정의하고, 코드에서 `config?.database`, `config?.hashVerification` 등으로 접근하면 됩니다. JWT는 `CoreModule.forHttpApi({ jwt: config?.jwt })` 로 넘기면 `ConfigValidator.validateJwtConfig` 시 env 검사를 건너뜁니다.
+
+---
+
+## 설정 루트·Config 로더
+
+모노레포·실행 위치와 관계없이 설정 디렉터리를 찾고, **한 번 로드 → env 동기화 → 전역 캐시 → getFullConfig / getServiceConfig** 패턴을 쓰려면 아래 API를 사용합니다.
+
+### resolveConfigRootDir(options?)
+
+`application.yml` / `application.yaml` 이 있는 디렉터리를 후보 순서대로 탐색해 반환합니다. 기본 후보는 모노레포 패턴(`libs/config/config`, `../../libs/config/config`, `../libs/config/config`, cwd)입니다.
+
+```typescript
+import { resolveConfigRootDir, loadApplicationYamlSync, DEFAULT_CONFIG_ROOT_CANDIDATES } from '@xfilecom/core-sdk';
+
+// 기본 (process.cwd() 기준 후보 탐색)
+const rootDir = resolveConfigRootDir();
+
+// 후보·파일명 지정
+const rootDir2 = resolveConfigRootDir({
+  cwd: process.cwd(),
+  candidates: ['libs/config/config', 'config', '.'],
+  configFilenames: ['application.yml', 'application.yaml'],
+});
+
+const config = loadApplicationYamlSync({ rootDir, env: process.env.NODE_ENV });
+```
+
+### createConfigLoader(options)
+
+한 번 로드한 config를 캐시하고, `getFullConfig()` / `getServiceConfig(serviceKey, overrides?)` 를 반환합니다. auth-service, mail-service, chat-service 등에서 동일한 패턴으로 사용할 수 있습니다.
+
+- **getFullConfig()**: 이미 로드된 full config 반환 (최초 호출 시 1회 로드 후 저장).
+- **getServiceConfig(serviceKey, overrides?)**: `full.common` + `full[serviceKey]` 병합. `overrides.portEnvKey` 가 있으면 `process.env[portEnvKey]` 로 `server.port` 덮어씀.
+
+```typescript
+import { createConfigLoader, resolveConfigRootDir } from '@xfilecom/core-sdk';
+
+const { getFullConfig, getServiceConfig } = createConfigLoader({
+  rootDir: resolveConfigRootDir(),
+  env: process.env.APP_PROFILE ?? (process.env.NODE_ENV === 'production' ? 'prod' : 'dev'),
+  syncEnvKeys: {
+    JWT_SECRET: 'auth-service.jwt.secret',
+    JWT_EXPIRES_IN: 'auth-service.jwt.expiresIn',
+  },
+  globalKey: 'auth-service',
+});
+
+// 서비스별 config (common + auth-service 병합, 포트는 AUTH_SERVICE_PORT 로 덮어쓰기)
+export const getAuthServiceConfig = () =>
+  getServiceConfig('auth-service', { portEnvKey: 'AUTH_SERVICE_PORT' });
+export { getFullConfig };
+```
+
+- **rootDir** 없으면 `resolveConfigRootDir()` 로 자동 해석.
+- **globalKey**: 동일 키로 캐시해 두어 재호출 시 같은 객체 반환.
+- YAML 구조 예: `common: { ... }, auth-service: { server: { port: 3001 }, jwt: { ... } }, mail-service: { ... }`.
+
+---
+
+## Crypto (비밀번호·조회용 해시)
+
+### PBKDF2 비밀번호 (usdt3·기존 DB 호환)
+
+저장 형식 `saltHex:hashHex`, 기본 pbkdf2-sha512 100_000회·64바이트. bcrypt와 형식이 달라 기존 usdt3 DB와 호환하려면 아래 API 사용.
+
+```typescript
+import {
+  pbkdf2HashPassword,
+  pbkdf2VerifyPassword,
+  PBKDF2_DEFAULT_ITERATIONS,
+  PBKDF2_DEFAULT_KEYLEN,
+  PBKDF2_DEFAULT_DIGEST,
+  type Pbkdf2Options,
+} from '@xfilecom/core-sdk';
+
+// 해시 (salt 미지정 시 랜덤 salt 자동 생성)
+const stored = pbkdf2HashPassword('myPassword');
+// 옵션 지정 시
+const stored2 = pbkdf2HashPassword('myPassword', undefined, {
+  iterations: 100_000,
+  keylen: 64,
+  digest: 'sha512',
+});
+
+// 검증
+const ok = pbkdf2VerifyPassword('myPassword', stored);
+const ok2 = pbkdf2VerifyPassword('myPassword', stored2, { iterations: 100_000, keylen: 64, digest: 'sha512' });
+```
+
+### 조회용 해시 (키 파생 — usdt3·기존 DB 호환)
+
+기존 DB가 **HMAC 키 = sha256(secret)** 방식이면 `keyDerivation: 'sha256'` 사용. YAML 프로필 또는 `lookupHash`/`compareLookupHash` 로 동일한 해시 생성.
+
+```typescript
+import { lookupHash, compareLookupHash, emailNormalizer, digitsNormalizer } from '@xfilecom/core-sdk';
+
+// secret을 sha256(secret)으로 파생해 HMAC (usdt3 호환)
+const emailHash = lookupHash('user@example.com', process.env.EMAIL_HASH_SECRET, {
+  keyDerivation: 'sha256',
+  normalizer: emailNormalizer,
+});
+const match = compareLookupHash('user@example.com', row.email_hash, process.env.EMAIL_HASH_SECRET, {
+  keyDerivation: 'sha256',
+  normalizer: emailNormalizer,
+});
+```
+
+YAML에서 프로필별로 지정할 때는 `hashVerification.profiles.email` 에 `keyDerivation: sha256` 추가 후 `hashByKey('email', ...)` 사용하면 동일한 결과.
+
+---
+
+## Hash verification
+
+이메일·전화번호·식별자 등 문자열을 YAML 설정 기반으로 HMAC 해시 후 저장/비교할 수 있습니다. **설정은 표준 위치의 application.yml** 에 두면 됩니다.
+
+### YAML 구조 (application.yml 에 추가)
+
+```yaml
+hashVerification:
+  default:
+    algorithm: sha256
+    secret: ${HASH_VERIFICATION_SECRET}
+    encoding: hex
+    keyDerivation: sha256   # usdt3 등 기존 DB 호환 시: HMAC 키 = sha256(secret)
+  profiles:
+    email:
+      secret: ${EMAIL_HASH_SECRET}
+      normalizer: email
+      keyDerivation: sha256
+    phone:
+      secret: ${PHONE_HASH_SECRET}
+      normalizer: digits
+      keyDerivation: sha256
+    userId:
+      secret: ${USER_ID_HASH_SECRET}
+    tenantId:
+      secret: ${TENANT_HASH_SECRET}
+```
+
+- **default**: 해당 키가 없을 때 사용하는 공통 설정.
+- **profiles**: 키별 설정. 새 키만 YAML에 추가하면 코드 수정 없이 `hashByKey(key, value, hv)` 로 처리 가능.
+- **normalizer**: `email`(trim+소문자), `digits`(숫자만). 생략 시 입력 그대로 해시.
+- **keyDerivation**: `none`(기본)=secret 그대로 HMAC 키로 사용. `sha256`=sha256(secret)을 HMAC 키로 사용(usdt3·기존 DB 호환).
+
+### 동적 키로 해시/비교 (권장)
+
+```typescript
+import { loadApplicationYaml, hashByKey, compareByKey } from '@xfilecom/core-sdk';
+
+const config = await loadApplicationYaml({ env: process.env.NODE_ENV });
+const hv = config?.hashVerification;
+
+const emailHash = hashByKey('email', 'user@example.com', hv);
+const phoneHash = hashByKey('phone', '010-1234-5678', hv);
+const userIdHash = hashByKey('userId', uid, hv);
+
+const match = compareByKey('email', plainEmail, row.email_hash, hv);
+```
+
+### 공통 API (config 직접 전달)
+
+```typescript
+import { hashValue, compareValue } from '@xfilecom/core-sdk';
+
+const hv = config?.hashVerification;
+const emailHash = hashValue('user@example.com', hv?.profiles?.email ?? hv?.email);
+const match = compareValue('user@example.com', row.email_hash, hv?.profiles?.email ?? hv?.email);
+```
+
+### 이메일 전용
+
+```typescript
+import { hashEmail, compareEmail } from '@xfilecom/core-sdk';
+
+const emailHash = hashEmail('User@Example.com', config?.hashVerification?.profiles?.email);
+const match = compareEmail('user@example.com', row.email_hash, config?.hashVerification?.profiles?.email);
+```
+
+- secret 없으면 `HASH_VERIFICATION_SECRET`(이메일 키는 `EMAIL_HASH_SECRET`) env 사용.
+- 내장 normalizer: `email`, `digits`. `BUILT_IN_NORMALIZERS`, `getProfileConfig`, `emailNormalizer`, `digitsNormalizer` export 됨.
+- **usdt3·기존 DB 호환**: 프로필에 `keyDerivation: sha256` 지정하거나, YAML 없이 `lookupHash`/`compareLookupHash(..., { keyDerivation: 'sha256' })` 사용.
+
+---
+
+## 기능 옵션
+
+CoreModule 옵션으로 기능별 on/off 가능. 미설정 시 **기본값 true**.
+
+| 옵션 | 설명 | 기본값 |
+|------|------|--------|
+| `database.auto` | DB 모듈 사용 | `true` |
+| `response.commonResponse` | `{ code, data, meta, error }` 형식 적용 | `true` |
+| `interceptors.logging` | 요청/응답 로깅 | `true` |
+| `interceptors.errorHandling` | 에러 인터셉터 | `true` |
+| `interceptors.responseTransform` | 응답 변환(CommonResponse) | `true` |
+| `interceptors.databaseCheck` | DB 연결 체크 | `true` |
+| `guards.jwt` | JWT 인증 가드 (forHttpApi/forHybrid 기본 true) | context별 |
+| `filters.exception` | AllExceptionsFilter | `true` |
+
+예: CommonResponse 끄기, 로깅/DB체크 끄기
+
+```typescript
+CoreModule.forHttpApi({
+  database: { schema },
+  response: { commonResponse: false },
+  interceptors: { logging: false, databaseCheck: false },
+})
+```
+
+---
+
+## Database
+
+### 스키마 정의 및 주입
+
+```typescript
+// database/schema.ts
+import { mysqlTable, int, varchar, timestamp } from 'drizzle-orm/mysql-core';
+
+export const users = mysqlTable('users', {
+  id: int('id').primaryKey().autoincrement(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  password: varchar('password', { length: 255 }).notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+
+export const schema = { users };
+```
+
+### 환경 변수
+
+`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_SSL`, `DB_CONNECTION_LIMIT`
+
+### DatabaseQuery
+
+`where`는 Drizzle `SQL` 또는 plain object(eq 조합) 지원.
+
+```typescript
+// select(options)
+const result = await this.dbQuery.select({
+  table: 'users',
+  fields: ['id', 'name', 'email'],
+  where: { email: 'test@example.com' },
+});
+
+// query() — pagination, sort, search
+const result = await this.dbQuery.query({
+  table: 'users',
+  fields: ['id', 'email'],
+  sort: [{ field: 'createdAt', order: 'desc' }],
+  pagination: { page: 1, limit: 10 },
+  search: [{ keyword: 'test', fields: ['email', 'name'] }],
+  where: { status: 'active' },
+});
+
+// insert / update / delete
+await this.dbQuery.insertOne({ table: 'users', fields: ['email', 'name'], values: data });
+await this.dbQuery.updateOne({ table: 'users', values: data, where: eq(users.id, id) });
+await this.dbQuery.deleteOne({ table: 'users', where: eq(users.id, id) });
+
+// findOne / findById / count / exists
+const user = await this.dbQuery.findOne('users', { where: { email: 'a@b.com' }, fields: ['id', 'email'] });
+const user = await this.dbQuery.findById('users', 1);
+const n = await this.dbQuery.count('users', { where: { status: 'active' } });
+const ok = await this.dbQuery.exists('users', { where: { email: 'a@b.com' } });
+```
+
+### ServiceHelpers (Drizzle 직접 사용)
+
+```typescript
+const db = this.helpers.getDb();
+const [user] = await db.select().from(users).where(eq(users.email, email)).limit(1);
+
+await this.helpers.withTransaction(async (tx) => {
+  await tx.insert(users).values({ email: 'a@b.com' });
+  await tx.insert(posts).values({ userId: 1, title: 'Hello' });
+});
+
+const paginationResult = this.helpers.createPaginationResult(items, total, page, limit);
+```
+
+---
+
+## Controller / Service 예시
+
+```typescript
+// Controller
+import { Controller, Get, Request, UseGuards } from '@nestjs/common';
+import { ControllerHelpers, Public, User, JwtUser, Roles, JwtAuthGuard, RolesGuard } from '@xfilecom/core-sdk';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly helpers: ControllerHelpers) {}
+
+  @Public()
+  @Get()
+  async findAll(@Request() req: any) {
+    const { page, limit } = this.helpers.parsePagination(req.query);
+    const users = await this.userService.findAll(page, limit);
+    return this.helpers.success(users, 'Users retrieved');
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @Get('me')
+  getMe(@User() user: JwtUser) {
+    return user;
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @Get('my-id')
+  getMyId(@User('sub') userId: string | number) {
+    return { userId };
+  }
+
+  @UseGuards(JwtAuthGuard, RolesGuard)
+  @Roles('admin')
+  @Get('admin')
+  adminOnly() {
+    return { message: 'admin only' };
+  }
+}
+
+// Service
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly helpers: ServiceHelpers,
+    private readonly dbQuery: DatabaseQuery,
+  ) {}
+
+  async findAll(page: number, limit: number) {
+    return this.dbQuery.query({
+      table: 'users',
+      fields: ['id', 'email', 'name'],
+      pagination: { page, limit },
+      sort: [{ field: 'id', order: 'desc' }],
+    });
+  }
+}
+```
+
+---
+
+## Guards · Decorators · Interceptors · Filters
+
+- **Guards**: `JwtAuthGuard`, `RolesGuard`
+- **Decorators**: `@Public()`, `@User()`, `@User('sub')`, `@Roles('admin', 'user')`
+- **Interceptors**: LoggingInterceptor, ErrorHandlingInterceptor, ResponseTransformInterceptor, DatabaseCheckInterceptor
+- **Filters**: AllExceptionsFilter
+- **응답 타입**: `CommonResponseDto`, `CommonErrorDto`, `PaginationMeta`, `ResponseMeta`
+
+**JWT 인증**: `JwtAuthGuard`는 `process.env.JWT_SECRET`을 참조합니다. YAML만 쓸 경우 `loadApplicationYaml({ syncEnvKeys: { JWT_SECRET: 'jwt.secret' } })` 로 config 값을 env에 채우면 Guard와 자연스럽게 연동됩니다. `CoreModule.forHttpApi({ jwt: { secret, expiresIn } })` 로 넘기면 ConfigValidator는 env 검사를 건너뜁니다. `passport-jwt` / `@nestjs/passport`는 **선택 의존성**이며, 없으면 경고 후 인증을 스킵합니다 (개발용). 프로덕션에서는 설치 권장.
+
+---
+
+## 기타 유틸
+
+- **ErrorUtils**: 에러 메시지/코드 처리
+- **LoggerHelpers**, **ILogWriter**, **ConsoleLogWriter**, **FileLogWriter**, **getLoggingConfigFromEnv**: 로깅
+- **ConfigValidator**: JWT/DB 설정 검증 (`validateJwtConfig(throwOnMissing?, jwtOptions?)` — `jwtOptions.secret` 이 있으면 env 검사 생략), **parseBoolean**, **parseNumber**, **parseArray** (쉼표 구분 문자열 → 배열)
+- **Env**: `getAppEnv()`, `isDevelopment()`, `isProduction()`, `isStaging()`, `currentAppEnv`, `isDev`, `isProd` (APP_ENV / NODE_ENV 기반)
+
+---
+
+## Database 연결 실패 시
+
+- 연결 실패해도 서버는 기동됩니다 (Graceful Degradation).
+- `.env`에 `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` 설정 후 재시도.
+- Config 직접 주입: `CoreModule.forHttpApi({ database: { config: { ... }, schema } })`.
+
+---
+
+## 수정 사항
+
+### JWT 설정 검증 (ConfigValidator)
+
+- `validateJwtConfig(throwOnMissing?, jwtOptions?)` 두 번째 인자 추가.
+- `options.jwt?.secret` 이 있으면 `process.env.JWT_SECRET` 검사를 건너뛰어 불필요한 경고를 내지 않음.
+- `CoreModule` 에서 JWT Guard 등록 시 `options.jwt` 를 넘기도록 변경 → YAML/옵션만으로 JWT 설정 시 경고 제거.
+
+### 설정 로드 시 env 동기화 (syncEnvKeys)
+
+- `loadApplicationYaml` / `loadApplicationYamlSync` 옵션에 `syncEnvKeys?: Record<string, string>` 추가.
+- 로드한 config의 dot 경로(예: `jwt.secret`) 값을 지정한 환경 변수명(예: `JWT_SECRET`)으로 `process.env`에 채움.
+- YAML만 사용해도 ConfigValidator, JwtAuthGuard 등이 `process.env`를 참조할 때 자연스럽게 연동 가능.
+
+### 설정 루트·Config 로더 (resolveConfigRootDir, createConfigLoader)
+
+- **resolveConfigRootDir(options?)**: application.yml 이 있는 디렉터리 탐색. 기본 후보: `libs/config/config`, `../../libs/config/config`, `../libs/config/config`, cwd. 모노레포·실행 위치 무관하게 동일 규칙 사용 가능.
+- **createConfigLoader(options)**: 한 번 로드 → env 동기화 → 전역 캐시(globalKey) → `getFullConfig()` / `getServiceConfig(serviceKey, { portEnvKey? })` 제공. auth-service, mail-service 등에서 config-root.ts·load-config.ts 대신 core-sdk만으로 동일 패턴 사용 가능.
+
+### 설정 소스 (configSource)
+
+- `configSource: 'yaml' | 'env' | 'yamlWithEnvOverrides'` 옵션 및 `CONFIG_SOURCE` 환경 변수로 .env vs YAML 선택 가능.
+- `configSource: 'env'` 시 YAML 없이 `process.env` 기반 config 객체 생성.
+
+### 환경 유틸 (Env)
+
+- `getAppEnv()`, `isDevelopment()`, `isProduction()`, `isStaging()`, `currentAppEnv`, `isDev`, `isProd` 추가 (APP_ENV / NODE_ENV 기반).
+
+### Crypto (비밀번호·조회용 해시)
+
+- **PBKDF2 비밀번호**: `pbkdf2HashPassword`, `pbkdf2VerifyPassword` — 저장 형식 `saltHex:hashHex`, 기본 100_000회·sha512·64바이트 (usdt3·기존 DB 호환).
+- **조회용 해시 키 파생**: `HashVerificationConfig.keyDerivation: 'none' | 'sha256'` — `sha256` 이면 HMAC 키로 sha256(secret) 사용 (usdt3·기존 email_hash 등과 동일).
+- **lookupHash / compareLookupHash**: YAML 없이 secret + keyDerivation 만으로 조회용 해시 생성/비교. `deriveKeySha256` export.
+
+### Hash verification
+
+- `hashVerification.profiles` + `hashByKey` / `compareByKey` 로 동적 키별 해시/비교 지원.
+- `keyDerivation: 'sha256'` 로 기존 DB와 동일한 해시 생성 가능.
+- `ConfigValidator.parseArray` 추가 (쉼표 구분 문자열 → 배열).
+
+### 문서
+
+- JWT 인증: `process.env` 참조, `syncEnvKeys` 연동, `passport-jwt` 선택 의존성 안내.
+- Auth 클라이언트: auth 모듈이 패키지에 포함되면 `index`에서 export 예정.
+
+---
+
+## 라이선스
+
+ISC

package/dist/core.module.d.ts

@@ -0,0 +1,39 @@
+import { DynamicModule } from '@nestjs/common';
+import { DatabaseConfig } from './database/database.module';
+import { LoggingInterceptorOptions } from './interceptors/logging.interceptor';
+import { ExceptionFilterOptions } from './filters/exception.filter';
+export interface CoreModuleOptions {
+    database?: {
+        auto?: boolean;
+        config?: DatabaseConfig;
+        schema?: any;
+    };
+    jwt?: {
+        secret?: string;
+        expiresIn?: string;
+        issuer?: string;
+        audience?: string;
+    };
+    response?: {
+        commonResponse?: boolean;
+    };
+    interceptors?: {
+        logging?: boolean | LoggingInterceptorOptions;
+        errorHandling?: boolean;
+        responseTransform?: boolean;
+        databaseCheck?: boolean;
+    };
+    guards?: {
+        jwt?: boolean;
+    };
+    filters?: {
+        exception?: boolean | ExceptionFilterOptions;
+    };
+    serviceType?: 'microservice' | 'http-api' | 'hybrid';
+}
+export declare class CoreModule {
+    static forRoot(options?: CoreModuleOptions): DynamicModule;
+    static forMicroservice(options?: CoreModuleOptions): DynamicModule;
+    static forHttpApi(options?: CoreModuleOptions): DynamicModule;
+    static forHybrid(options?: CoreModuleOptions): DynamicModule;
+}