# Bảo mật

Một tích hợp Hạ Tầng giữ nhiều secret: API key, secret ký webhook, mã bí mật định danh của chat và secret key của Thanh toán. Trang này là danh sách kiểm tra để giữ an toàn từng loại, thu hẹp những gì một secret bị lộ có thể làm, và xác minh mọi thứ gửi tới server của bạn.

## Các loại thông tin xác thực

| Loại | Dạng | Đặt ở đâu | Bí mật? |
|---|---|---|---|
| API key | `ht_...` | Chỉ ở server của bạn | Có |
| Secret ký webhook | `whsec_...` | Chỉ ở server của bạn | Có |
| Mã bí mật định danh của chat | hiện một lần trên trang website | Chỉ ở server của bạn | Có |
| Secret key của Thanh toán | `sk_...` | Chỉ ở server của bạn | Có |
| Site id của chat | `site_...` | Trang web và ứng dụng của bạn | Không, công khai |
| Khoá ứng dụng di động | `hak_...` | Trong bản build ứng dụng | Không, nhưng thu hồi được |

Mọi thứ được đánh dấu bí mật không bao giờ được xuất hiện trong JavaScript chạy trên trình duyệt, ứng dụng di động, plugin công khai, kho Git hay phiếu hỗ trợ. Giữ chúng trong biến môi trường hoặc trình quản lý secret.

## API key

- **Chỉ cấp cho key những scope nó cần.** Server chỉ gửi email cần `email:send`, không cần `*` ([Xác thực API](https://hatang.dev/vi/docs/guides/getting-started/authentication.md#scopes)).
- **Mỗi dịch vụ hoặc môi trường một key**, đặt tên theo nơi nó chạy. Như vậy bạn thu hồi một key mà không đụng tới key khác, và cột **Dùng lần cuối** cho biết key nào còn được dùng.
- **Giới hạn key.** Khoá key email vào một **Tên miền gửi**. Chỉ khi key buộc phải chạy trong trình duyệt mới điền **Origin trình duyệt**; request từ origin khác bị từ chối ([Key bị giới hạn](https://hatang.dev/vi/docs/guides/getting-started/authentication.md#restricted-keys)).
- **Xoay key** khi người từng biết key nghỉ việc, khi nghi lộ, và theo lịch định kỳ: tạo key mới, triển khai, rồi thu hồi key cũ. Key bị thu hồi ngừng hoạt động trong vòng một phút.
- **Kiểm tra việc sử dụng.** **Email → Logs** liệt kê mọi request API kèm key đã gọi, user agent, status và body. Lời gọi hay endpoint lạ là dấu hiệu key bị lộ.

Key chỉ hiện một lần khi tạo. Hạ Tầng chỉ lưu bản băm, nên key bị mất không khôi phục được; hãy tạo key mới.

## Webhook

- **Xác minh mọi lượt gửi.** Kiểm tra chữ ký trên body gốc và từ chối lượt gửi có timestamp cũ quá 300 giây ([Webhook](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md)). Lượt gửi được xác thực bằng chữ ký, không phải bằng nơi nó xuất phát. Header `user-agent: hatang-webhooks/1.0` chỉ mang tính thông tin.
- **Dùng endpoint HTTPS.** Hạ Tầng chỉ gửi tới URL `https` công khai và không đi theo chuyển hướng.
- **Xoay secret ký** khi nó có thể đã lộ. Trong 24 giờ sau khi xoay, lượt gửi mang chữ ký của cả secret cũ lẫn mới, nên bạn triển khai mà không mất sự kiện.
- **Lọc trùng theo `svix-id`** để lượt gửi lại hay thử lại không kích hoạt cùng một hành động hai lần.
- **Lời gọi IPN của Thanh toán** tới `ipn_url` được ký riêng, bằng `Hatang-Signature` và secret key của môi trường. Xem [Xác minh IPN](https://hatang.dev/vi/docs/guides/payments/verify-ipn.md).

## Danh tính trong chat

- **Xác minh danh tính.** Khi website hoặc ứng dụng cho chat biết người dùng là ai, hãy kèm `hash` (HMAC-SHA256 của user id với mã bí mật định danh của site) tính ở server. Không có nó, ai cũng có thể tự nhận là khách hàng khác và đọc lịch sử của họ ([Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md)).
- **Giữ mã bí mật định danh ở server**, và xoay bằng **Tạo mới & hiển thị** nếu nghi lộ. Hash tạo bằng mã cũ hết hiệu lực ngay.
- **Giới hạn nơi widget chạy.** Widget chỉ khởi động trên tên miền của website, các tên miền phụ và các **Origin được phép thêm** bạn liệt kê. Gỡ các origin xem trước và localhost không còn dùng.
- **Thu hồi khoá ứng dụng di động** không còn dùng, sau khi đã phát hành bản ứng dụng dùng khoá mới.

## Thanh toán

- Giữ secret key của từng môi trường ở server và kiểm tra `environment` trong mọi sự kiện Thanh toán và IPN, để thanh toán development không bao giờ kích hoạt đơn hàng thật.
- Key `ht_test_` không bao giờ chạm được dữ liệu production. Quyền vào production được chọn theo từng request bằng `Hatang-Environment` ([Môi trường Thanh toán](https://hatang.dev/vi/docs/guides/payments/environments.md)).

## SMTP relay

SMTP relay tại `smtp.hatang.dev:5870` dùng STARTTLS, tên đăng nhập `hatang` và mật khẩu là một API key. Chỉ cấp cho key đó scope `email:send`. Sau 10 lần đăng nhập sai từ một địa chỉ IP, relay từ chối mọi lần thử tiếp theo từ địa chỉ đó trong 15 phút.

## Đội ngũ

- Cấp cho nhân viên mức quyền thấp nhất đủ để làm việc, và chỉ cấp quyền **Developer** (tạo được API key và webhook) cho người cần ([Nhân viên và phân quyền](https://hatang.dev/vi/help/account/employees-and-roles)).
- Gỡ người nghỉ việc ở **Cài đặt → Nhân viên**, và xoay các API key, secret họ từng biết. Key của họ vẫn chạy cho tới khi bạn thu hồi, vì key không gắn với một người.

## Khi một secret bị lộ

1. **API key:** thu hồi ở **Cài đặt → API Keys**, tạo key thay thế, và xem **Email → Logs** để tìm các lời gọi không phải của bạn.
2. **Secret webhook:** xoay secret và triển khai secret mới trong vòng 24 giờ.
3. **Mã bí mật định danh:** bấm **Tạo mới & hiển thị** và cập nhật server.
4. **Secret key Thanh toán:** thay mới ở **Cài đặt thanh toán → Khoá tích hợp** và cập nhật server.

## Bước tiếp theo

- [Xác thực API](https://hatang.dev/vi/docs/guides/getting-started/authentication.md)
- [Webhook](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md)
- [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md)

Source: https://hatang.dev/vi/docs/guides/getting-started/security