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

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

태그 논리

항목의 태그는 AND로 결합됩니다. 항목은 그 모든 태그가 방문자의 증명에 있을 때만 검색됩니다. 방문자의 증명은 원하는 만큼 권한을 담을 수 있으며, 매칭은 그 전체에 대해 한 번에 이루어집니다.

AND는 의도된 설계입니다. 하나만 일치하는 방식이라면 항목에 태그를 추가할수록 볼 수 있는 범위가 넓어져서, 문서를 두 그룹으로 좁히려던 것이 실제로는 두 그룹 모두에게 전부 공개하는 결과가 됩니다. 모두 일치 방식에서는 추가한 태그가 언제나 더 좁히는 방향으로만 작동하므로, 실수가 안전한 쪽으로 기웁니다.

“둘 중 아무거나” 표현하기

해당 차원을 항목에서 빼십시오. 모든 방문자의 증명이 지역을 담고 있다면, 지역 태그가 없는 문서는 모든 지역에서 이용할 수 있고 나머지 태그는 그대로 적용됩니다. 즉 premium만 붙은 항목은 “지역 무관, 프리미엄 구독자만”을 뜻합니다.

차원을 넘나드는 진짜 선택이 필요하다면 — 예를 들어 북부×기본 또는 남부×프리미엄만 — 항목을 조합마다 하나씩 두 번 추가하거나, 두 대상 모두에게 서버가 증명에 포함시키는 공통 태그를 부여하세요.

제한

• 지식 항목당 최대 20개 태그
• 방문자 한 명의 증명에 최대 50개 태그
• 태그당 50자. 증명이 쉼표로 구분된 문자열이므로 쉼표와 세로 막대는 사용할 수 없습니다

나중에 태그 변경하기

기존 항목의 태그는 다시 업로드하지 않고 교체할 수 있습니다. 변경은 다음 질문부터 적용되며 콘텐츠 자체는 재처리되지 않습니다.

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

빈 목록을 보내면 항목이 다시 공개됩니다. 대시보드의 Access Tags 페이지에서 직접 편집할 수도 있습니다.

보장되는 것

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

알아두면 좋은 점

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