Access Tags

Przegląd

Nie każda treść jest dla wszystkich: dokumenty tylko dla członków, materiały dla konkretnego regionu, zasoby płatnych pakietów. Access Tags pozwala jednemu chatbotowi bezpiecznie obsługiwać różne grupy odbiorców. Nadajesz elementowi wiedzy tag i od tej chwili element jest niewidoczny dla każdego odwiedzającego — poza tymi, których strona przedstawia ten tag, podpisany przez Twój własny serwer. Ograniczenie jest egzekwowane w naszym zapytaniu wyszukującym, zanim model AI w ogóle weźmie udział. Odwiedzający bez tagu nie wydobędzie treści sprytnymi pytaniami, bo dla niego nigdy nie została pobrana.

Jak to działa

1. Ty tagujesz elementy wiedzy - na stronie Access Tags albo bezpośrednio przez API; elementy bez tagów nadal działają dla wszystkich
2. Twój serwer podpisuje tagi każdego odwiedzającego - gdy zalogowany członek wczytuje Twoją stronę, Twój back-end ustala jego uprawnienia i podpisuje je tajnym kluczem, który posiadasz tylko Ty
3. Widżet wysyła podpisane poświadczenie - podróżuje z każdą wiadomością na czacie; przeglądarka jedynie je przenosi i nie może go zmienić bez zniszczenia podpisu
4. My weryfikujemy i filtrujemy - ważny podpis odblokowuje elementy z pasującymi tagami; brakujące, zmienione lub wygasłe poświadczenie oznacza, że odwiedzający dostaje tylko treści publiczne

Konfiguracja

Włącz funkcję na stronie Access Tags w swoim panelu — klucz podpisujący zostanie wygenerowany za Ciebie. Przechowuj go tylko na swoim serwerze; każdy, kto go ma, może tworzyć ważne poświadczenia.

Otaguj treści na tej samej stronie albo podczas przesyłania elementów przez API:

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

Następnie niech Twój serwer umieści podpisane poświadczenie obok snippetu widżetu. Podpisywana wiadomość to lista tagów rozdzielonych przecinkami, połączona pionową kreską z czasem wygaśnięcia, jeśli go używasz:

<?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>

Ten sam podpis w Node.js i Pythonie:

// 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()

Bez czasu wygaśnięcia podpisujesz sam ciąg tagów. Z czasem wygaśnięcia poświadczenie przestaje działać w chwili jego upływu — przydatne, gdy uprawnienia można odebrać, bo odwiedzający musi przeładować stronę, którą kontrolujesz, aby dostać świeże poświadczenie.

Logika tagów

Tagi elementu łączą się przez ORAZ: element jest pobierany tylko wtedy, gdy każdy jego tag występuje w poświadczeniu odwiedzającego. Poświadczenie odwiedzającego może nieść dowolnie wiele uprawnień, a dopasowanie odbywa się względem wszystkich naraz.

ORAZ jest celowe. Przy dopasowaniu «którykolwiek» dodanie drugiego tagu do elementu poszerzyłoby krąg widzących, więc zawężenie dokumentu do dwóch grup w istocie opublikowałoby go w całości obu. Przy dopasowaniu «wszystkie» każdy dodany tag może tylko dalej zawężać, więc pomyłka wypada po bezpiecznej stronie.

Wyrażanie «którykolwiek z»

Pomiń ten wymiar przy elemencie. Jeśli poświadczenie każdego odwiedzającego niesie jego region, dokument bez tagu regionu jest dostępny dla wszystkich regionów, a pozostałe jego tagi nadal obowiązują. Element otagowany wyłącznie premium oznacza więc «dowolny region, tylko abonenci premium».

Dla prawdziwego wyboru między wymiarami — na przykład północ-z-podstawowym albo południe-z-premium i nic więcej — dodaj element dwa razy, po jednej kombinacji, albo daj obu grupom wspólny tag, który Twój serwer umieszcza w ich poświadczeniach.

Limity

• Do 20 tagów na element wiedzy
• Do 50 tagów w poświadczeniu jednego odwiedzającego
• 50 znaków na tag; przecinki i pionowe kreski są niedozwolone, ponieważ poświadczenie to ciąg rozdzielany przecinkami

Późniejsza zmiana tagów

Tagi można zastąpić na istniejącym elemencie bez ponownego wysyłania go. Zmiana obowiązuje od następnego pytania — sama treść nie jest przetwarzana ponownie.

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

Wyślij pustą listę, aby element znów stał się publiczny. Tagi możesz też edytować ręcznie na stronie Access Tags w swoim panelu.

Co jest gwarantowane

• Egzekwowanie po stronie serwera - filtr działa wewnątrz naszego zapytania do bazy przy wyszukiwaniu; dla nieautoryzowanych odwiedzających elementy z tagami nie trafiają do kontekstu AI, więc nie ma czemu wyciec
• Wszędzie fail-closed - brak podpisu, zły podpis, wygasłe poświadczenie, wyłączona funkcja, obniżony plan: w każdym z tych przypadków odwiedzający dostaje wyłącznie treści publiczne, nigdy więcej
• Przeglądarka nie podrobi dostępu - edycja tagów w narzędziach deweloperskich niszczy podpis; klucz posiada tylko Twój serwer
• Twoja logika uprawnień pozostaje Twoja - nigdy nie wiemy, jak decydujesz, kto dostaje który tag; sprawdzamy tylko, że potwierdził to Twój serwer

Warto wiedzieć

• Access Tags to autoryzacja, User Context to personalizacja - użyj User Context, aby opowiedzieć AI o członku; użyj Access Tags, aby kontrolować, z jakiej wiedzy AI może korzystać
• Zaindeksowana treść witryny jest zawsze publiczna - pochodzi z Twojej publicznej strony, więc nie ma czego ograniczać; tagi dotyczą elementów tekstowych, plików i API
• Tagi elementu łączą się przez ORAZ - zobacz Logikę tagów powyżej; każdy tag elementu musi znajdować się w poświadczeniu odwiedzającego
• Nowy klucz unieważnia wszystkie stare poświadczenia - zrób to, jeśli klucz mógł wyciec, a potem zaktualizuj strony, by podpisywały nowym
• Nazwy tagów zależą od Ciebie - do 20 na element, po 50 znaków, bez przecinków i pionowych kresek; nigdy nie pojawiają się w czacie widocznym dla odwiedzających