tbmaasme

ไลบรารีสำหรับงานเข้ารหัสข้อมูลแบบ Asymmetric (RSA) และ Hybrid Encryption ที่ออกแบบมาให้ใช้งานง่าย พร้อมระบบจัดการ Key และ Configuration ผ่าน Environment Variables

A streamlined library for Asymmetric (RSA) and Hybrid Encryption, featuring built-in Key management and Configuration via Environment Variables.

✨ คุณสมบัติเด่น / Key Features

• Hybrid Encryption: เข้ารหัสข้อมูลด้วย AES และปกป้อง Symmetric Key ด้วย RSA
• Automatic Key Resolution: ค้นหา Key File ให้อัตโนมัติในรูปแบบมาตรฐาน (src/keys/... หรือ /etc/keys/...)
• Runtime Configuration: รองรับการตั้งค่าผ่าน .env และ process.env โดยอัตโนมัติ
• Prepared Hybrid Contexts: เตรียม Key/Config ครั้งเดียวแล้วนำไปใช้ซ้ำใน hot path
• Bilingual Documentation: เอกสารรองรับทั้งภาษาไทยและภาษาอังกฤษ
• Type Safety: พัฒนาด้วย TypeScript พร้อม Type Definitions ครบถ้วน

📦 การติดตั้ง / Installation

npm install tbmaasme
# หรือ
yarn add tbmaasme

GSD for Codex

โปรเจ็กต์นี้รองรับการติดตั้ง GSD แบบ project-local ไว้ใน ./.codex/ เพื่อให้ workflow ติดมากับโค้ดและใช้ซ้ำได้ในเครื่องอื่น

• Initial install source: get-shit-done-cc from gsd-build/get-shit-done
• Installed runtime: Codex
• Installed scope: local to this repository
• Project script จะ normalize .codex/config.toml ให้เป็น path แบบ relative ต่อ repo

Useful commands:

npm run gsd:install
npm run gsd:update

หลังจากเปิด repo นี้ใน Codex แล้ว สามารถใช้คำสั่งอย่าง:

$gsd-help
$gsd-new-project

🚀 เริ่มต้นใช้งานอย่างรวดเร็ว / Quick Start

ตัวอย่างการใช้งานแบบพื้นฐานสำหรับทั้ง Symmetric และ Hybrid Encryption:

import { 
  encryptText, 
  decryptText, 
  encryptHybridData, 
  decryptHybridData,
  generateKeyPair 
} from "tbmaasme";

// 1. Symmetric Encryption (AES)
const { key, encrypted } = encryptText("Hello World");
const decrypted = decryptText(encrypted, key);

// 2. Hybrid Encryption (RSA + AES)
// สร้าง Key Pair จำลอง (ในงานจริงควรใช้ไฟล์ Key จากระบบ)
const { _publicKey, _privateKey } = generateKeyPair();

const hybrid = encryptHybridData("system-a", "Secret Payload", undefined, undefined, {
  publicKey: _publicKey
});

// ถอดรหัส Symmetric Key จาก secretCode
const symKey = decryptHybridData(hybrid.secretCode, {
  privateKey: _privateKey,
  systemName: "system-a"
});

// นำ symKey ไปถอดรหัสข้อมูล payload ต่อได้ด้วย decryptText
const finalResult = decryptText(hybrid.encryptData, symKey);

Fast Path สำหรับงานที่เรียกซ้ำจำนวนมาก

ถ้า encrypt/decrypt อยู่ใน request path ให้สร้าง context ไว้ตอน bootstrap แล้ว reuse:

import {
  createHybridEncryptor,
  createHybridDecryptor,
  decryptText
} from "tbmaasme";

const encryptor = createHybridEncryptor("system-a", {
  publicKeyPath: "/etc/keys/system-a/public.key",
  rsaScheme: "oaep",
  oaepHash: "sha256",
  algorithm: "aes-256-cbc",
  ivLength: 16,
  aesHexKeyLength: 64,
  ivHexLength: 32
});

const decryptor = createHybridDecryptor({
  privateKeyPath: "/etc/keys/system-a/private.key",
  systemName: "system-a",
  rsaScheme: "oaep",
  oaepHash: "sha256"
});

const encrypted = encryptor.encrypt("Secret Payload");
const symKey = decryptor.decrypt(encrypted.secretCode);
const payload = decryptText(encrypted.encryptData, symKey);

ค่า default ของ key file cache จะใช้ไฟล์ที่อ่านแล้วซ้ำทันทีเพื่อลด filesystem call. ถ้าต้องการตรวจจับการหมุน key file ทุกครั้ง ให้ส่ง keyFileCacheMode: "stat".

⚙️ การตั้งค่า / Configuration

Environment Variables

ไลบรารีจะอ่านค่าจากไฟล์ .env ใน baseDir (เริ่มต้นคือ process.cwd()) และจะ fallback ไปที่ process.env

| Key | Description | Default (Base64 Decoded) | |-----|-------------|-------------------------| | TBMAASME_SYMMETRIC_ALGORITHM | Algorithm สำหรับ AES | aes-256-cbc | | TBMAASME_IV_LENGTH | ความยาวของ IV (bytes) | 16 | | TBMAASME_RSA_SCHEME | RSA Padding Scheme (oaep | pkcs1) | oaep | | TBMAASME_OAEP_HASH | Hash algorithm สำหรับ OAEP | sha256 | | TBMAASME_RSA_MODULUS_LENGTH | ความยาวของ RSA Key (bits) | 2048 | | NODE_ENV | โหมดการทำงาน (development เพื่อใช้ path ใน src/keys) | development | | KEY_ENV | สภาพแวดล้อมของ Key (dev, stg, iwt, prod) | dev |

ตัวอย่างส่งค่า env เป็น param ใน function

ใช้วิธีนี้เมื่ออยากควบคุมค่า env รายครั้งผ่าน options ของฟังก์ชัน:

import {
  encryptHybridData,
  decryptHybridData,
  type KeyEnv,
  type NodeEnv
} from "tbmaasme";

const keyEnv: KeyEnv = ["dev", "stg", "iwt", "prod"].includes(process.env.KEY_ENV ?? "")
  ? (process.env.KEY_ENV as KeyEnv)
  : "dev";

const nodeEnv: NodeEnv = process.env.NODE_ENV === "production"
  ? "production"
  : "development";

const baseDir = process.cwd();

const hybrid = encryptHybridData(
  "system-a",
  "Secret Payload",
  undefined,
  undefined,
  {
    baseDir,
    keyEnv,
    nodeEnv,
    rsaScheme: process.env.TBMAASME_RSA_SCHEME as "oaep" | "pkcs1" | undefined,
    oaepHash: process.env.TBMAASME_OAEP_HASH
  }
);

const symKey = decryptHybridData(hybrid.secretCode, {
  baseDir,
  keyEnv,
  nodeEnv,
  systemName: "system-a"
});

📂 โครงสร้างไฟล์ Key / Key Structure

เมื่อรันในโหมด NODE_ENV=development ไลบรารีจะค้นหา Key ภายใต้ src/keys/ ตามรูปแบบดังนี้:

src/keys/
└── <system>/
    └── <keyEnv>/
        ├── tbma_<system>_<keyEnv>_public.key  (หรือ .cer/.crt สำหรับบางระบบ)
        └── tbma_<system>_<keyEnv>_private.key

• Special Cases: ระบบ botbtt ใช้ .cer, ระบบ sec ใช้ .crt
• Production Mode: เมื่อ NODE_ENV=production จะค้นหาที่ /etc/keys/<system>/...

🛠️ API Reference

Key Generation

• generateKeyPair(options?): สร้าง RSA Key Pair (PEM Format)
  • options: { rsaScheme, modulusLength, baseDir }

Symmetric Encryption (AES)

• encryptText(text, key?, iv?, options?): เข้ารหัส text (output: iv:payload)
• decryptText(encrypted, key, options?): ถอดรหัสข้อมูล

Hybrid Encryption

• encryptHybridData(system, text, key?, iv?, options?): เข้ารหัสข้อมูลและห่อหุ้ม key ด้วย RSA
• decryptHybridData(secretCode, options?): ถอดรหัสเพื่อเอา Symmetric Key กลับมา
• createHybridEncryptor(system, options?): เตรียม public key/config ครั้งเดียวสำหรับ encrypt ซ้ำ
• createHybridDecryptor(options?): เตรียม private key/config ครั้งเดียวสำหรับ decrypt ซ้ำ

Utilities

• resolveKeyPath(type, system, options?): ค้นหา path ของ key file
• compress(data) / decompress(data): ย่อ/ขยายข้อมูล (zlib)
• CryptoException: Custom error class สำหรับงาน encryption

📜 Scripts

npm run build      # Build library (tsup)
npm run test       # Run tests (vitest)
npm run typecheck  # Run TypeScript compiler check

📄 License

MIT © puwarunp