Access Tags

Tổng quan

Không phải nội dung nào cũng dành cho tất cả: tài liệu chỉ dành cho hội viên, tài liệu theo khu vực, tài nguyên của các cấp trả phí. Với Access Tags, một chatbot duy nhất phục vụ các nhóm đối tượng khác nhau một cách an toàn. Bạn gắn thẻ vào một mục kiến thức, và từ khoảnh khắc đó mục ấy vô hình với mọi khách truy cập — trừ những người mà trang của họ xuất trình thẻ đó, được ký bởi chính máy chủ của bạn. Hạn chế được thực thi trong truy vấn truy xuất của chúng tôi, trước cả khi mô hình AI tham gia. Khách truy cập không có thẻ không thể moi nội dung bằng câu hỏi khôn khéo, vì với họ nội dung chưa bao giờ được truy xuất.

Cách hoạt động

1. Bạn gắn thẻ các mục kiến thức - trên trang Access Tags hoặc trực tiếp qua API; các mục không thẻ vẫn hoạt động cho mọi người
2. Máy chủ của bạn ký thẻ của từng khách truy cập - khi một hội viên đã đăng nhập tải trang của bạn, back-end xác định quyền của họ và ký bằng khóa bí mật chỉ bạn nắm giữ
3. Widget gửi bằng chứng đã ký - nó đi cùng mọi tin nhắn trò chuyện; trình duyệt chỉ vận chuyển và không thể sửa mà không phá vỡ chữ ký
4. Chúng tôi xác minh và lọc - chữ ký hợp lệ mở khóa các mục có thẻ khớp; bằng chứng thiếu, bị sửa hoặc hết hạn nghĩa là khách truy cập chỉ nhận nội dung công khai

Cách thiết lập

Bật tính năng trên trang Access Tags trong bảng điều khiển — khóa ký được tạo tự động. Chỉ giữ trên máy chủ của bạn; ai có nó đều có thể tạo bằng chứng hợp lệ.

Gắn thẻ nội dung ngay trên trang đó, hoặc khi gửi các mục qua API:

POST /api/v1/knowledge/text/
{
  "title": "Members-only price list",
  "content": "...",
  "website_id": "123",
  "access_tags": ["premium"]
}

Sau đó để máy chủ in bằng chứng đã ký cạnh đoạn mã widget. Thông điệp cần ký là danh sách thẻ phân tách bằng dấu phẩy, nối bằng gạch đứng với thời gian hết hạn khi bạn dùng:

<?php
$tags    = "members,premium";          // this visitor's entitlements
$expires = time() + 3600;              // unix seconds, optional but recommended
$sig     = hash_hmac("sha256", $tags . "|" . $expires, $SECRET);
?>
<script>
window.Asyntai = window.Asyntai || {};
window.Asyntai.accessTags = "<?php echo $tags; ?>";
window.Asyntai.accessTagsExpires = "<?php echo $expires; ?>";
window.Asyntai.accessTagsSignature = "<?php echo $sig; ?>";
</script>

Cùng chữ ký đó trong Node.js và Python:

// Node.js
const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET)
                  .update(tags + "|" + expires).digest("hex");

# Python
import hmac, hashlib
sig = hmac.new(SECRET.encode(), f"{tags}|{expires}".encode(),
               hashlib.sha256).hexdigest()

Không có thời hạn, chỉ ký chuỗi thẻ. Có thời hạn, bằng chứng ngừng hoạt động ngay khi quá hạn — hữu ích khi quyền có thể bị thu hồi, vì khách truy cập phải tải lại trang do bạn kiểm soát để nhận bằng chứng mới.

Logic của thẻ

Các thẻ của một mục kết hợp theo VÀ: mục chỉ được truy xuất khi mọi thẻ trên nó xuất hiện trong bằng chứng của khách truy cập. Bằng chứng của khách có thể mang bao nhiêu quyền tùy ý, và việc đối chiếu diễn ra trên tất cả cùng lúc.

VÀ là chủ ý. Với cách đối chiếu «ít nhất một», thêm thẻ thứ hai vào một mục sẽ mở rộng người được xem, nên việc thu hẹp tài liệu về hai nhóm thực chất lại công bố trọn vẹn cho cả hai. Với cách đối chiếu «tất cả», mỗi thẻ bạn thêm chỉ có thể siết chặt thêm, nên sai sót ngả về phía an toàn.

Diễn đạt «bất kỳ cái nào»

Hãy bỏ chiều đó khỏi mục. Nếu bằng chứng của mọi khách đều mang khu vực của họ, thì tài liệu không có thẻ khu vực sẽ dùng được cho mọi khu vực, trong khi các thẻ còn lại vẫn áp dụng. Vậy một mục chỉ gắn premium nghĩa là «mọi khu vực, chỉ người đăng ký premium».

Với lựa chọn thực sự xuyên chiều — chẳng hạn bắc-với-cơ-bản hoặc nam-với-premium, và không gì khác — hãy thêm mục hai lần, mỗi lần một tổ hợp, hoặc cấp cho cả hai nhóm một thẻ chung mà máy chủ của bạn đưa vào bằng chứng của họ.

Giới hạn

• Tối đa 20 thẻ cho mỗi mục kiến thức
• Tối đa 50 thẻ trong bằng chứng của một khách
• 50 ký tự mỗi thẻ; không cho phép dấu phẩy và gạch đứng, vì bằng chứng là chuỗi phân tách bằng dấu phẩy

Đổi thẻ về sau

Có thể thay thẻ trên một mục đã có mà không cần tải lên lại. Thay đổi áp dụng từ câu hỏi kế tiếp — bản thân nội dung không bị xử lý lại.

POST /api/v1/knowledge/<id>/tags/
{
  "access_tags": ["premium"]
}

Gửi danh sách rỗng để mục trở lại công khai. Bạn cũng có thể sửa thẻ thủ công trên trang Access Tags trong bảng điều khiển.

Những gì được đảm bảo

• Thực thi phía máy chủ - bộ lọc chạy trong truy vấn cơ sở dữ liệu khi truy xuất; với khách không được ủy quyền, các mục có thẻ hoàn toàn vắng mặt trong ngữ cảnh của AI, nên không có gì để rò rỉ
• Fail-closed ở mọi nơi - không chữ ký, chữ ký sai, bằng chứng hết hạn, tính năng tắt, gói bị hạ cấp: trong mọi trường hợp đó, khách truy cập chỉ nhận nội dung công khai, không bao giờ hơn
• Trình duyệt không thể giả mạo quyền truy cập - sửa thẻ trong công cụ nhà phát triển làm hỏng chữ ký; chỉ máy chủ của bạn giữ khóa
• Logic quyền của bạn vẫn là của bạn - chúng tôi không bao giờ biết bạn quyết định ai nhận thẻ nào ra sao; chúng tôi chỉ xác minh máy chủ của bạn đã xác nhận điều đó

Nên biết

• Access Tags là ủy quyền, User Context là cá nhân hóa - dùng User Context để kể cho AI về hội viên; dùng Access Tags để kiểm soát AI được dựa vào kiến thức nào
• Nội dung trang web được thu thập luôn công khai - nó đến từ trang công khai của bạn nên không có gì để hạn chế; thẻ áp dụng cho các mục văn bản, tệp và API
• Các thẻ của một mục kết hợp theo VÀ - xem Logic của thẻ ở trên; mọi thẻ của mục phải có trong bằng chứng của khách
• Tạo lại khóa vô hiệu hóa mọi bằng chứng cũ - hãy làm nếu khóa có thể đã lộ, rồi cập nhật các trang để ký bằng khóa mới
• Tên thẻ do bạn đặt - tối đa 20 mỗi mục, mỗi thẻ 50 ký tự, không dấu phẩy hay gạch đứng; chúng không bao giờ xuất hiện trong đoạn chat khách nhìn thấy