Giao diện

Hướng dẫn cài đặt và sử dụng — Request Encryption ​

Tổng quan ​

@digiforce-nc/plugin-request-encryption mã hóa query parameters trong URL bằng Base64 encoding để bảo vệ thông tin nhạy cảm (filter conditions, IDs, tham số nghiệp vụ) khỏi bị đọc trực tiếp trên thanh địa chỉ hoặc access log.

Lưu ý: Đây là mã hóa ở tầng obfuscation (Base64), không phải mã hóa mật mã (AES/RSA). Mục đích chính là ngăn người dùng hoặc hệ thống trung gian đọc được nội dung query string, không phải bảo vệ chống tấn công mật mã.

Yêu cầu ​

  • Server Digiforce đang chạy
  • HTTPS đã được cấu hình (khuyến nghị)

Bước 1: Kích hoạt Plugin ​

Vào Settings → Plugin Manager, tìm plugin-request-encryption và bật. Khởi động lại server.

Sau khi kích hoạt:

  • Server middleware tự động đăng ký (trước bodyParser)
  • Client interceptor tự động bật cho mọi API request

Bước 2: Kiểm tra hoạt động ​

Plugin hoạt động hoàn toàn trong suốt — không cần cấu hình thêm. Sau khi bật:

  1. Mở Developer Tools → Network tab trong trình duyệt
  2. Thực hiện thao tác bất kỳ trên giao diện (lọc dữ liệu, mở trang, v.v.)
  3. Quan sát URL request — query string sẽ có dạng:
/api/users:list?__encoded__=eyJmaWx0ZXIiOnsiJGFuZCI6W3sicm9sZSI6eyIkZXEiOiJhZG1pbiJ9fV19fQ==

Thay vì hiển thị rõ ràng:

/api/users:list?filter={"$and":[{"role":{"$eq":"admin"}}]}
  1. Giao diện vẫn hoạt động bình thường — dữ liệu hiển thị đúng

Cơ chế hoạt động chi tiết ​

Phía Client (Encode) ​

Plugin đăng ký Axios request interceptor để mã hóa tất cả params trước khi gửi:

Hàm base64EncodeUnicode() hỗ trợ mã hóa cả ký tự Unicode (tiếng Việt, tiếng Trung, v.v.) — sử dụng encodeURIComponent + btoa.

Phía Server (Decode) ​

Plugin đăng ký Koa middleware (chạy trước bodyParser) để giải mã:

Xử lý lỗi ​

Plugin được thiết kế fail-safe — nếu giải mã thất bại, request vẫn được xử lý bình thường:

LỗiHành vi
Giải mã Base64 thất bạiLog lỗi, dùng query gốc
JSON parse thất bạiLog lỗi, dùng query gốc
Kết quả không phải object hợp lệLog cảnh báo, dùng query gốc
Không có __encoded__Bỏ qua, dùng query gốc

API Client bên ngoài ​

Nếu có ứng dụng bên ngoài gọi API Digiforce, cần implement logic encode tương tự:

JavaScript / Node.js ​

javascript
function base64EncodeUnicode(str) {
  return btoa(
    encodeURIComponent(str).replace(
      /%([0-9A-F]{2})/g,
      (_, p1) => String.fromCharCode(parseInt(p1, 16))
    )
  );
}

const params = { filter: { role: { $eq: 'admin' } } };
const encoded = base64EncodeUnicode(JSON.stringify(params));

fetch(`/api/users:list?__encoded__=${encoded}`);

Python ​

python
import base64
import json
import urllib.parse

def base64_encode_unicode(s):
    encoded = urllib.parse.quote(s, safe='')
    binary = bytes(
        int(encoded[i+1:i+3], 16) if encoded[i] == '%' else ord(encoded[i])
        for i in range(len(encoded))
        if encoded[max(0,i-1):i+1].find('%') == -1 or encoded[i] == '%'
    )
    return base64.b64encode(s.encode('utf-8')).decode('ascii')

params = {"filter": {"role": {"$eq": "admin"}}}
encoded = base64.b64encode(json.dumps(params).encode('utf-8')).decode('ascii')
# Gửi request với ?__encoded__=<encoded>

Không muốn encode (bypass) ​

Nếu ứng dụng bên ngoài không implement encoding, vẫn có thể gửi request bình thường — server chỉ giải mã khi phát hiện tham số __encoded__. Request không có __encoded__ được xử lý như bình thường.

Lưu ý quan trọng ​

  • Plugin tự động xử lý mã hóa/giải mã — không cần thay đổi code trong các plugin hoặc workflow khác
  • Chỉ mã hóa query parameters (URL query string) — request body (POST/PUT/PATCH) không bị ảnh hưởng
  • Hỗ trợ Unicode đầy đủ — query chứa tiếng Việt, tiếng Nhật, v.v. đều hoạt động
  • Hiệu năng: overhead ~1ms mỗi request (encode/decode Base64 rất nhanh)
  • Không thay thế HTTPS — Base64 dễ dàng giải mã; HTTPS bảo vệ dữ liệu thực sự trên đường truyền
  • Access log server sẽ ghi URL dạng encoded — giảm rò rỉ thông tin nhạy cảm qua log
  • Middleware đăng ký với option { before: 'bodyParser' } — đảm bảo chạy sớm nhất có thể