Access Tags

개요

모든 콘텐츠가 모두를 위한 것은 아닙니다. 회원 전용 문서, 지역별 자료, 유료 등급 리소스 등이 그렇습니다. Access Tags를 사용하면 챗봇 하나로 서로 다른 대상을 안전하게 지원할 수 있습니다. 지식 항목에 태그를 붙이는 순간, 그 항목은 모든 방문자에게 보이지 않게 됩니다 — 고객님의 서버가 서명한 그 태그를 페이지에서 제시하는 방문자만 예외입니다. 제한은 AI 모델이 관여하기 전, 저희 검색 쿼리에서 강제됩니다. 태그가 없는 방문자는 교묘한 질문으로도 콘텐츠를 빼낼 수 없습니다. 애초에 검색되지 않았기 때문입니다.

작동 방식

1. 지식 항목에 태그를 붙입니다 - Access Tags 페이지에서 또는 API로 직접. 태그 없는 항목은 계속 모두에게 작동합니다
2. 서버가 각 방문자의 태그에 서명합니다 - 로그인한 회원이 페이지를 열면 백엔드가 그 권한을 판단하고, 고객님만 가진 비밀 키로 서명합니다
3. 위젯이 서명된 증명을 전송합니다 - 모든 채팅 메시지와 함께 전달됩니다. 브라우저는 운반만 할 뿐, 서명을 깨뜨리지 않고는 변경할 수 없습니다
4. 저희가 검증하고 필터링합니다 - 유효한 서명은 태그가 일치하는 항목을 열어 줍니다. 증명이 없거나 조작되었거나 만료되었으면 방문자는 공개 콘텐츠만 받습니다

설정 방법

대시보드의 Access Tags 페이지에서 기능을 켜세요 — 서명 시크릿이 자동 생성됩니다. 서버에만 보관하세요. 이것을 가진 사람은 누구나 유효한 증명을 만들 수 있습니다.

태그는 같은 페이지에서 지정하거나 API로 항목을 보낼 때 지정합니다:

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

그다음 서버가 위젯 스니펫 옆에 서명된 증명을 출력하게 하세요. 서명할 메시지는 쉼표로 구분된 태그 목록이며, 만료 시간을 쓸 경우 세로 막대로 연결합니다:

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

Node.js와 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()

만료 없이 쓰려면 태그 문자열만 서명하세요. 만료가 있으면 그 시각이 지나는 순간 증명이 작동을 멈춥니다 — 권한이 회수될 수 있을 때 유용합니다. 방문자가 새 증명을 받으려면 고객님이 관리하는 페이지를 다시 로드해야 하기 때문입니다.

보장되는 것

• 서버 측 강제 - 필터는 검색 시 데이터베이스 쿼리 안에서 실행됩니다. 승인되지 않은 방문자에게는 태그 항목이 AI 컨텍스트에 아예 없으므로 유출될 것이 없습니다
• 모든 경우에 fail-closed - 서명 없음, 잘못된 서명, 만료된 증명, 꺼진 기능, 다운그레이드된 요금제: 어느 경우든 방문자는 공개 콘텐츠만 받으며 그 이상은 절대 받지 않습니다
• 브라우저는 접근을 위조할 수 없습니다 - 개발자 도구에서 태그를 수정하면 서명이 깨집니다. 키는 고객님의 서버에만 있습니다
• 권한 로직은 고객님의 것 - 누구에게 어떤 태그를 줄지 어떻게 정하는지 저희는 알 수 없습니다. 서버가 그렇게 표명했다는 것만 검증합니다

알아두면 좋은 점

• Access Tags는 인가, User Context는 개인화 - 회원에 대해 AI에 알리려면 User Context를, AI가 참조할 수 있는 지식을 제어하려면 Access Tags를 사용하세요
• 크롤링된 웹사이트 콘텐츠는 항상 공개 - 공개 사이트에서 온 것이므로 제한할 것이 없습니다. 태그는 텍스트, 파일, API 항목에 적용됩니다
• 일치하는 태그 하나면 충분합니다 - 태그가 두 개인 항목은 둘 중 하나만 가진 방문자에게도 제공됩니다
• 시크릿 재생성은 모든 이전 증명을 무효화합니다 - 시크릿이 유출됐을 수 있다면 실행하고, 이후 페이지가 새 것으로 서명하도록 업데이트하세요
• 태그 이름은 자유입니다 - 항목당 최대 20개, 각 50자, 쉼표와 세로 막대는 사용 불가. 방문자가 보는 채팅에는 절대 나타나지 않습니다