Tham chiếu kỹ thuật

EncryptionField — Kiểu field trong database

Thuộc tính	Giá trị
Field type	`encryption`
DB column type	`TEXT`
Lưu trữ	Ciphertext (AES encrypted)
Key storage	Field metadata (`options`)

Field đăng ký vào database ORM thông qua module @digiforce-nc/database, cho phép hệ thống tự động tạo cột TEXT khi migration.

Encrypt / Decrypt trên Write / Read

Quá trình ghi (encrypt)

Client gửi plaintext
  → Hook beforeCreate / beforeUpdate
    → Lấy encryption key từ field metadata
    → AES encrypt(plaintext, key)
    → Lưu ciphertext vào DB

Quá trình đọc (decrypt)

Query từ DB trả về ciphertext
  → Hook afterFind
    → Lấy encryption key từ field metadata
    → AES decrypt(ciphertext, key)
    → Trả plaintext về client

Custom Operators

Plugin đăng ký hai operators cho phép query trên dữ liệu mã hóa:

Operator	SQL tương đương	Cách hoạt động
`$encryptionEq`	`WHERE col = ?`	Encrypt giá trị tìm kiếm bằng cùng key, so sánh với ciphertext trong DB
`$encryptionNe`	`WHERE col != ?`	Encrypt giá trị, so sánh khác

Giới hạn: chỉ hỗ trợ so sánh chính xác (equality). Không thể dùng LIKE, range, hoặc sorting trên ciphertext.

Per-field Encryption Keys

Mỗi field encryption lưu key riêng trong metadata (field options):

typescript

{
  name: 'ssn',
  type: 'encryption',
  options: {
    encryptionKey: 'base64-encoded-aes-key',
  },
}

Key được tạo tự động khi thêm field (nếu chưa có).
Hooks beforeCreate và beforeUpdate kiểm tra và cập nhật key khi cần.
Cho phép mỗi field dùng key khác nhau — compromise một key không ảnh hưởng field khác.

Server Hooks

Hook	Thời điểm	Hành động
`beforeCreate`	Trước khi tạo bản ghi mới	Encrypt giá trị plaintext
`beforeUpdate`	Trước khi cập nhật bản ghi	Encrypt giá trị mới
`afterFind`	Sau khi đọc từ DB	Decrypt ciphertext thành plaintext

Hooks đăng ký vào model của collection chứa encryption field, chỉ xử lý các cột có type encryption.

EncryptionError Handler

Plugin đăng ký error handler với plugin-error-handler để bắt EncryptionError:

Lỗi	Nguyên nhân	Xử lý
Decrypt failed	Key sai hoặc ciphertext bị corrupt	Trả lỗi rõ ràng thay vì crash
Key not found	Field metadata thiếu encryption key	Thông báo cấu hình lại field

CLI Key Rotation

Plugin cung cấp CLI command để xoay vòng encryption key mà không mất dữ liệu:

Quy trình key-rotation:
1. Đọc tất cả bản ghi chứa field encryption
2. Decrypt bằng key cũ
3. Re-encrypt bằng key mới
4. Cập nhật ciphertext trong DB
5. Lưu key mới vào field metadata

Sử dụng khi:

Nghi ngờ key bị lộ.
Chính sách bảo mật yêu cầu xoay key định kỳ.
Nâng cấp thuật toán mã hóa.

Sơ đồ luồng tổng quan

┌─────────┐    plaintext    ┌──────────┐    ciphertext    ┌──────────┐
│ Client  │ ──────────────→ │  Server  │ ──────────────→  │ Database │
│   UI    │ ←────────────── │  Hooks   │ ←────────────── │  (TEXT)  │
└─────────┘    plaintext    └──────────┘    ciphertext    └──────────┘