Access Tags

Panoramica

Non tutti i contenuti sono per tutti: documenti riservati ai soci, materiale specifico per regione, risorse dei livelli a pagamento. Con Access Tags un solo chatbot serve pubblici diversi in sicurezza. Metti un tag su un elemento di conoscenza e da quel momento l'elemento è invisibile a ogni visitatore — tranne quelli la cui pagina presenta quel tag, firmato dal tuo stesso server. La restrizione è applicata nella nostra query di recupero, prima ancora che il modello di IA entri in gioco. Un visitatore senza il tag non può estrarre il contenuto con domande astute, perché per lui non è mai stato recuperato.

Come funziona

1. Tu metti i tag sugli elementi di conoscenza - nella pagina Access Tags o direttamente via API; gli elementi senza tag continuano a funzionare per tutti
2. Il tuo server firma i tag di ogni visitatore - quando un socio autenticato carica la tua pagina, il tuo back-end stabilisce i suoi diritti e li firma con una chiave segreta che possiedi solo tu
3. Il widget invia l'attestazione firmata - viaggia con ogni messaggio della chat; il browser la trasporta soltanto e non può alterarla senza rompere la firma
4. Noi verifichiamo e filtriamo - una firma valida sblocca gli elementi con tag corrispondenti; un'attestazione assente, manomessa o scaduta significa che il visitatore riceve solo contenuti pubblici

Come configurarlo

Attiva la funzione nella pagina Access Tags della tua dashboard — viene generata per te una chiave di firma. Conservala solo sul tuo server; chiunque la possieda può creare attestazioni valide.

Metti i tag ai contenuti nella stessa pagina, oppure quando invii gli elementi tramite l'API:

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

Poi fai stampare al tuo server l'attestazione firmata accanto allo snippet del widget. Il messaggio da firmare è l'elenco di tag separati da virgole, unito con una barra verticale all'orario di scadenza quando ne usi uno:

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

La stessa firma in Node.js e 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()

Senza scadenza, firma solo la stringa dei tag. Con la scadenza, un'attestazione smette di funzionare nel momento in cui scade — utile quando i diritti possono essere revocati, perché il visitatore deve ricaricare una pagina che controlli tu per ottenerne una fresca.

Logica dei tag

I tag di un elemento si combinano in AND: l'elemento è recuperabile solo quando ogni tag su di esso compare nell'attestazione del visitatore. L'attestazione di un visitatore può portare quanti diritti vuoi, e il confronto avviene su tutti insieme.

L'AND è voluto. Con un confronto «almeno uno», aggiungere un secondo tag a un elemento ne allargherebbe la visibilità: restringere un documento a due gruppi lo pubblicherebbe di fatto per intero a entrambi. Con il confronto «tutti», ogni tag aggiunto può solo restringere ulteriormente, così un errore cade dal lato sicuro.

Esprimere «uno qualsiasi tra»

Ometti la dimensione sull'elemento. Se l'attestazione di ogni visitatore porta la sua area, un documento senza tag di area è disponibile per tutte le aree, mentre gli altri suoi tag continuano a valere. Un elemento taggato solo premium significa quindi «qualsiasi area, solo abbonati premium».

Per una vera scelta tra dimensioni — per esempio nord-con-base oppure sud-con-premium, e nient'altro — aggiungi l'elemento due volte con una combinazione ciascuna, oppure dai a entrambi i pubblici un tag condiviso che il tuo server include nelle loro attestazioni.

Limiti

• Fino a 20 tag per elemento di conoscenza
• Fino a 50 tag nell'attestazione di un singolo visitatore
• 50 caratteri per tag; virgole e barre verticali non sono ammesse, perché l'attestazione è una stringa separata da virgole

Modificare i tag in seguito

I tag possono essere sostituiti su un elemento esistente senza ricaricarlo. La modifica vale dalla domanda successiva — il contenuto stesso non viene rielaborato.

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

Invia una lista vuota per rendere di nuovo pubblico un elemento. Puoi anche modificare i tag a mano nella pagina Access Tags della tua dashboard.

Cosa è garantito

• Applicazione lato server - il filtro gira dentro la nostra query al database durante il recupero; per i visitatori non autorizzati gli elementi con tag sono assenti dal contesto dell'IA, quindi non c'è nulla che possa trapelare
• Fail-closed ovunque - nessuna firma, firma errata, attestazione scaduta, funzione spenta, piano declassato: in ognuno di questi casi il visitatore riceve solo contenuti pubblici, mai di più
• Il browser non può falsificare l'accesso - modificare i tag negli strumenti sviluppatore rompe la firma; solo il tuo server possiede la chiave
• La tua logica dei diritti resta tua - non sappiamo mai come decidi chi riceve quale tag; verifichiamo solo che il tuo server lo abbia affermato

Buono a sapersi

• Access Tags è autorizzazione, User Context è personalizzazione - usa User Context per raccontare all'IA chi è il socio; usa Access Tags per controllare a quale conoscenza l'IA può attingere
• Il contenuto scansionato del sito è sempre pubblico - proviene dal tuo sito pubblico, quindi non c'è nulla da limitare; i tag si applicano a elementi di testo, file e API
• I tag di un elemento si combinano in AND - vedi Logica dei tag sopra; ogni tag dell'elemento deve essere presente nell'attestazione del visitatore
• Rigenerare la chiave invalida tutte le vecchie attestazioni - fallo se la chiave potrebbe essere trapelata, poi aggiorna le tue pagine perché firmino con la nuova
• I nomi dei tag li scegli tu - fino a 20 per elemento, 50 caratteri ciascuno, senza virgole né barre verticali; non compaiono mai nella chat vista dai visitatori