[24.11.26 / TASK-40] Feature - token encrytion (#2)

* feature: token 관련 기본 디렉토리, 모듈 세팅
* feature: token 테스트 완료, 관련 세팅 업데이트 완료
* modify: 타이니한 주석 정도 수정

Author: Nuung

.env.sample

@@ -4,3 +4,15 @@ DB_PASSWORD=""
 DB_HOST=""
 DB_PORT=5432
 DB_NAME=""
+
+# 토큰 단방향 암호화 전용 핵심 키
+AES_KEY_0=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_1=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_2=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_3=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_4=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_5=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_6=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_7=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_8=01a8b93c17f8d6e4fba3c5d91e7a6f45
+AES_KEY_9=01a8b93c17f8d6e4fba3c5d91e7a6f45

README.md

@@ -10,6 +10,9 @@
 
 ```bash
 pnpm install
+
+# 만약 pnpm 이 없다면 
+brew install pnpm
 ```
 
 2. 환경 변수 설정
@@ -27,11 +30,11 @@ pnpm dev
 
 ## 실행 가능한 명령어
 
-```
-pnpm dev: 개발 서버 실행
-pnpm test: 테스트 실행
-pnpm lint: 린트 검사
-pnpm lint:fix: 린트 자동 수정
+```bash
+pnpm dev  # 개발 서버 실행
+pnpm test  # 테스트 실행
+pnpm lint  # 린트 검사
+pnpm lint:fix  # 린트 자동 수정
 ```
 
 ## Project Structure

src/modules/__test__/test.aes.encryption.test.ts

@@ -0,0 +1,63 @@
+import crypto from 'crypto';
+import AESEncryption from '../token_encryption/aes_encryption';
+
+describe('AESEncryption 클래스 테스트', () => {
+  const validKey = crypto.randomBytes(32).toString('hex').slice(0, 32); // 32바이트 키 생성
+  const invalidKey = crypto.randomBytes(16).toString('hex').slice(0, 16); // 16바이트 키 생성 (유효하지 않음)
+  const aes = new AESEncryption(validKey);
+  const sampleText = 'This is a test message for AES encryption!';
+
+  test('암호화 후 복호화 결과가 원본과 동일해야 한다', () => {
+    const encrypted = aes.encrypt(sampleText);
+    const decrypted = aes.decrypt(encrypted);
+    expect(decrypted).toBe(sampleText);
+  });
+
+  test('잘못된 키 길이를 사용하면 오류가 발생해야 한다', () => {
+    expect(() => new AESEncryption(invalidKey)).toThrow(
+      '키는 256비트(32바이트)여야 합니다.'
+    );
+  });
+
+  test('암호화 결과는 base64 형식이어야 한다', () => {
+    const encrypted = aes.encrypt(sampleText);
+    expect(() => Buffer.from(encrypted, 'base64')).not.toThrow();
+  });
+
+  test('동일한 데이터를 여러 번 암호화해도 결과가 달라야 한다 (IV 사용 확인)', () => {
+    const encrypted1 = aes.encrypt(sampleText);
+    const encrypted2 = aes.encrypt(sampleText);
+    expect(encrypted1).not.toBe(encrypted2);
+  });
+
+  test('빈 문자열도 암호화 및 복호화가 정상적으로 동작해야 한다', () => {
+    const encrypted = aes.encrypt('');
+    const decrypted = aes.decrypt(encrypted);
+    expect(decrypted).toBe('');
+  });
+
+  test('큰 입력 데이터를 암호화 및 복호화해도 원본과 동일해야 한다', () => {
+    const largeText = 'A'.repeat(10_000); // 10,000자 문자열
+    const encrypted = aes.encrypt(largeText);
+    const decrypted = aes.decrypt(encrypted);
+    expect(decrypted).toBe(largeText);
+  });
+
+  test('유니코드 문자열도 암호화 및 복호화가 정상적으로 동작해야 한다', () => {
+    const unicodeText = '안녕하세요! AES 암호화 테스트입니다. 🚀';
+    const encrypted = aes.encrypt(unicodeText);
+    const decrypted = aes.decrypt(encrypted);
+    expect(decrypted).toBe(unicodeText);
+  });
+
+  test('잘못된 암호화 데이터는 복호화 시 오류가 발생해야 한다', () => {
+    const invalidData = 'invalid_encrypted_data';
+    expect(() => aes.decrypt(invalidData)).toThrow();
+  });
+
+  test('손상된 암호화 데이터는 복호화 시 오류가 발생해야 한다', () => {
+    const encrypted = aes.encrypt(sampleText);
+    const corruptedData = encrypted.slice(0, -4) + 'abcd'; // 암호화 데이터 끝부분 손상
+    expect(() => aes.decrypt(corruptedData)).toThrow();
+  });
+});

src/modules/token_encryption/aes_encryption.ts

@@ -0,0 +1,63 @@
+import crypto from 'crypto';
+
+/**
+ * AES 암호화/복호화 유틸리티 클래스
+ * AES-256-CBC 알고리즘을 사용하여 데이터를 암호화하고 복호화합니다.
+ */
+class AESEncryption {
+  private readonly key: Buffer;
+
+  /**
+   * AES 암호화 클래스를 초기화합니다.
+   * @param {string} key - 256비트(32바이트) 암호화 키
+   * @throws {Error} 키가 256비트가 아닌 경우 예외를 발생시킵니다.
+   */
+  constructor(key: string) {
+    if (key.length !== 32) {
+      throw new Error('키는 256비트(32바이트)여야 합니다.');
+    }
+    this.key = Buffer.from(key, 'utf-8');
+  }
+
+  /**
+   * 주어진 문자열을 AES-256-CBC 알고리즘으로 암호화합니다.
+   * @param {string} plaintext - 암호화할 문자열
+   * @returns {string} base64로 인코딩된 암호화 데이터
+   */
+  encrypt(plaintext: string): string {
+    const iv = crypto.randomBytes(16); // 16바이트 IV 생성
+    const cipher = crypto.createCipheriv('aes-256-cbc', this.key, iv);
+
+    // PKCS7 패딩은 node 에서 자동 처리
+    const encrypted = Buffer.concat([
+      cipher.update(Buffer.from(plaintext, 'utf-8')),
+      cipher.final(),
+    ]);
+
+    // IV와 암호화된 데이터를 결합하여 base64로 반환
+    return Buffer.concat([iv, encrypted]).toString('base64');
+  }
+
+  /**
+   * AES-256-CBC 알고리즘으로 암호화된 데이터를 복호화합니다.
+   * @param {string} encryptedData - base64로 인코딩된 암호화 데이터
+   * @returns {string} 복호화된 문자열
+   */
+  decrypt(encryptedData: string): string {
+    const encryptedBuffer = Buffer.from(encryptedData, 'base64');
+    const iv = encryptedBuffer.slice(0, 16); // 암호화 데이터에서 IV 추출
+    const encryptedContent = encryptedBuffer.slice(16); // 암호화된 본문 추출
+
+    const decipher = crypto.createDecipheriv('aes-256-cbc', this.key, iv);
+
+    // 복호화된 데이터를 반환
+    const decrypted = Buffer.concat([
+      decipher.update(encryptedContent),
+      decipher.final(),
+    ]);
+
+    return decrypted.toString('utf-8');
+  }
+}
+
+export default AESEncryption;