@digiforce-nc/plugin-field-encryption

Plugin cung cấp kiểu field mã hóa — tự động encrypt dữ liệu trước khi lưu vào database (AES) và decrypt khi đọc ra, hỗ trợ per-field encryption key, custom operators cho query, và CLI key-rotation.

Plugin này làm gì?

Hãy hình dung: khác với mask (chỉ che trên UI), plugin này mã hóa thực sự dữ liệu trong database. Cột lưu trữ là TEXT chứa ciphertext — không ai đọc được dữ liệu gốc khi truy cập trực tiếp DB. Server tự động encrypt khi ghi và decrypt khi đọc, mỗi field có thể dùng encryption key riêng.

Bốn nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Encrypt/Decrypt	AES mã hóa khi ghi, giải mã khi đọc — transparent với application
2	Per-field key	Mỗi field có thể cấu hình encryption key riêng trong metadata
3	Custom operators	`$encryptionEq`, `$encryptionNe` — so sánh giá trị mã hóa trong query
4	Key rotation CLI	Command line để xoay vòng encryption key mà không mất dữ liệu

Kiến trúc

Tổng quan 3 tầng

Tầng	Vai trò	Thành phần
Client	Nhập/hiển thị plaintext bình thường	`InputEncryptionFieldWidget`, `DisplayEncryptionFieldWidget`
Server	Encrypt khi ghi, decrypt khi đọc	Field type `encryption`, hooks, operators
Database	Lưu ciphertext dạng TEXT	Cột với giá trị mã hóa AES

Luồng Encrypt khi ghi

Field type `encryption`

Thuộc tính	Giá trị
DB column type	TEXT
Encrypt algorithm	AES
Key storage	Field metadata (options)
Hooks	`beforeCreate`, `beforeUpdate` (encrypt), `afterFind` (decrypt)

Custom operators

Operator	Mô tả
`$encryptionEq`	So sánh bằng — encrypt giá trị cần tìm rồi so với ciphertext trong DB
`$encryptionNe`	So sánh khác — ngược lại `$encryptionEq`

Key management & CLI

Mỗi field encryption có thể có key riêng, lưu trong field metadata. Hooks beforeCreate và beforeUpdate tự động tạo/cập nhật key khi cần. Plugin cung cấp CLI command key-rotation để xoay vòng key (decrypt bằng key cũ → re-encrypt bằng key mới) mà không mất dữ liệu.

Error handling

Plugin đăng ký với plugin-error-handler để bắt EncryptionError (decrypt thất bại do key sai hoặc dữ liệu corrupt).

Ví dụ sử dụng

Cấu hình field encryption

typescript

const ssnField = {
  name: 'ssn',
  type: 'encryption',
  interface: 'encryption',
  uiSchema: {
    type: 'string',
    title: 'Số CCCD',
    'x-component': 'InputEncryption',
  },
};

Query với custom operator

typescript

const result = await repository.find({
  filter: {
    ssn: { $encryptionEq: '001234567890' },
  },
});

Thành phần client

Thành phần	Mô tả
`EncryptionFieldInterface`	Định nghĩa interface cho field encryption
`InputEncryptionFieldWidget`	Widget nhập liệu (hiển thị plaintext)
`DisplayEncryptionFieldWidget`	Widget hiển thị (giải mã từ server)

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — hook encrypt/decrypt
`@digiforce-nc/database`	Database ORM — đăng ký field type
`@digiforce-nc/client`	Client framework — đăng ký component
`@digiforce-nc/plugin-error-handler`	Xử lý EncryptionError