Xfeatures Athenaeum

Xfeatures 애플리케이션, 사람, AI 에이전트를 연결하는 보안 지식 계층.

조직의 모든 애플리케이션, 사람, AI 에이전트를 위한 인증된 단일 지식·검색 서비스입니다. 정확한 사실은 D1에, 문서는 R2에 저장되며, 의미 기반 검색은 Cloudflare AI Search를 통해 수행됩니다 — 그리고 어떤 것도 이들에 직접 접근하지 않습니다.

호출자는 REST, Workers RPC 또는 MCP로 통신합니다. Athenaeum은 모든 호출에서 누가 요청하는지, 무엇을 볼 수 있는지 판별한 다음, 결과를 반환하기 전에 모든 결과를 실시간 데이터베이스와 대조해 다시 확인합니다.

Caller ──▶ REST / RPC / MCP ──▶ authenticate ▸ authorize ▸ audit ──▶ D1 · R2 · AI Search

소스 공개 — 사유(proprietary) 소프트웨어이지 오픈소스가 아닙니다. 이 코드는 Xfeatures Proprietary Source License에 따라 읽거나, 클론하거나, 비공개로 평가할 수 있습니다. 프로덕션 서비스로 실행하거나, 상업적으로 운영하거나, 수정된 사본을 재배포하려면 별도의 서면 허가가 필요합니다. 아래 라이선스를 참조하세요.

왜 필요한가

각 에이전트에게 고유한 데이터베이스, 문서 사본, 직접 만든 RAG 파이프라인을 주면 에이전트마다 지식 베이스가 하나씩 생깁니다 — 각각은 서로 다른 방식으로 낡아가고, 어느 것도 접근 통제되어 있지 않습니다. Athenaeum은 그 대안입니다. 하나의 코퍼스(corpus), 하나의 권한 모델, 하나의 감사 추적(audit trail), 그리고 에이전트별로 그 일부를 제공합니다.

Related MCP server: Volterra Knowledge Engine

보장 내용

• 신원은 결코 클라이언트가 주장하는 대로 받아들여지지 않습니다. 호출자는 자격 증명(credential)을 제시하며, 권한은 검증된 신원을 기준으로 Athenaeum 자체 데이터베이스에서 가져옵니다. 토큰의 범위(scope)를 편집해도 얻을 것은 없습니다.

• 분류(classification)와 도메인은 모든 호출에서 강제됩니다. INTERNAL 등급으로 support 도메인에 접근이 허용된 지원 에이전트는 같은 도메인에 속한 RESTRICTED 문서를 볼 수 없습니다 — 그 문서가 존재한다는 사실조차 알 수 없습니다.

• 검색 인덱스는 권위(authoritative)를 가지지 않습니다. 검색된 모든 청크(chunk)는 반환되기 전에 실시간 데이터베이스 행과 다시 검증됩니다. 따라서 낡았거나 변조된 인덱스는 콘텐츠를 유출할 수 없고, 대체된 버전이 현재 버전의 신원으로 제공될 수 없습니다.

• 검색된 지식은 증거이지 지시가 아닙니다. Athenaeum은 LLM을 호출하지 않습니다. 인용이 포함된 구절을 반환하며, 호출한 에이전트가 답변을 종합하고 그 콘텐츠를 신뢰할 수 없는 것으로 취급할 책임이 있습니다.

• 게시에는 사람이 필요합니다. 에이전트는 문서를 작성하고 검토를 위해 제출할 수 있습니다. 어떤 전송 방식도 게시 수단을 노출하지 않습니다.

• 수동으로 삭제되는 것은 없습니다. 문서는 휴지통으로 이동하고, 72시간 동안 복원할 수 있으며, 예약된 작업에 의해 영구 삭제됩니다 — 버튼으로 삭제되는 일은 없습니다.

두 종류의 지식

Athenaeum은 정확한 사실과 의미 기반 지식을 다르게 저장합니다. 실패하는 방식이 다르기 때문입니다.

가격이 필요한 에이전트는 가격을 검색해서는 안 됩니다. 반드시 정확해야 하는 숫자는 사실 조회(fact lookup)이고, 사람이 읽을 구절은 문서입니다. 유사도 검색에서 그럴듯해 보이는 잘못된 가격을 얻어내는 것이 바로 이 분리가 막고자 하는 실패입니다.

각 저장소의 용도

• D1이 권위(authority)입니다. 사실, 문서 메타데이터, 카탈로그, 에이전트, 역할, 권한, 할당량(quota), 감사 추적이 모두 여기에 있습니다. 모든 접근 결정은 D1에서 내려지며, 캐시나 인덱스에서 결코 내려지지 않습니다.

• R2는 표준 문서 콘텐츠를 버전별로 하나의 불변(immutable) 객체로 보관합니다. 키(key)는 서버에서 생성되며, 사람이 쉽게 찾아볼 수 있도록 분류와 도메인이 포함됩니다 — 이 키는 명시적으로 보안 경계가 아닙니다. 버킷(bucket)은 공개적으로 접근할 수 없기 때문입니다.

• AI Search는 R2에 대한 인덱스일 뿐, 그 이상도 아닙니다. 어디를 찾아야 하는지에 대한 힌트이며, 호출자가 무엇을 볼 수 있는지에 대한 권위는 결코 아닙니다.

Athenaeum의 위치

flowchart LR
    people["People"] --> hq["Xfeatures HQ<br/>control plane"]
    agents["AI agents<br/>and applications"] --> ath
    hq -- "machine credential,<br/>authorized like anyone else" --> ath["Xfeatures Athenaeum"]
    ath -- "token introspection" --> acc["Xfeatures Account<br/>identity"]
    hq --> acc
    ath --> stores[("D1 · R2 · AI Search")]

• Xfeatures Account는 Xfeatures 생태계의 신원 플랫폼입니다. 누가 호출하는지만 답할 뿐 그 외에는 아무것도 하지 않습니다. Athenaeum은 검사(introspection)된 신원을 받아 자체 데이터베이스에서 권한을 판별합니다. Account 토큰은 당신이 누구인지 증명할 수 있지만, 여기서는 아무것도 얻지 못합니다. (Account는 별도의 비공개 시스템입니다. 이 저장소는 그것이 노출하는 공개 계약 -- RFC 7662 introspection -- 을 문서화할 뿐, 구현을 다루지는 않습니다.)

• Xfeatures HQ는 사람들이 문서를 관리하고, 검토·게시하며, 접근을 통제하는 컨트롤 플레인(control plane)입니다. HQ는 Athenaeum 내부에서 특별한 지위를 갖지 않습니다 — 자체 머신 자격 증명으로 인증하며 모든 호출에서 권한을 부여받습니다. HQ의 주체(principal)를 해지하면 Account 신원에는 영향을 주지 않은 채 HQ만 차단됩니다.

보안 모델

다섯 가지 속성은 각각 관례가 아닌 코드로 강제됩니다.

1. 신원은 판별되며 결코 제시된 대로 수용되지 않습니다. 권한은 모든 호출에서 검증된 신원을 기준으로 한 최신 D1 읽기에서 나옵니다. 호출자가 보내는 어떤 것도 자신이 볼 수 있는 범위를 넓힐 수 없습니다.

2. 모든 읽기에는 두 개의 독립적인 관문(gate)이 있습니다. 범위(scope) 권한(documents.read.<domain>) 그리고 분류 권한(knowledge.classification.<TIER>). 둘 중 하나만 있으면 거부됩니다.

3. 출처(provenance)는 추론이 아니라 기록됩니다. 모든 문서는 소스 유형과 참조를 가지며, 모든 버전은 누가 왜 작성했는지를 기록하고, 모든 인증된 호출 — 허용되든 거부되든 — 감사 이벤트를 남깁니다.

4. 버전은 불변입니다. 편집은 버전을 추가하며 기존 버전을 다시 쓰지 않습니다. 롤백(rollback)은 이전 버전을 새 버전으로 다시 게시합니다. 이력은 증거이므로 어떤 것도 이를 덮어쓰지 않습니다.

5. 현재 버전 조정(reconciliation). 검색 결과는 청크의 소스 객체가 문서의 현재 버전이고 그리고 실시간 행이 여전히 활성 상태이며 호출자가 볼 수 있는 분류를 여전히 유지하고 있는 경우에만 제공됩니다. 낡은 인덱스는 대체된 버전을 현재 버전의 신원으로 유출할 수 없으며, 방금 아카이브되거나 재분류되거나 휴지통으로 이동된 것을 유출할 수도 없습니다.

검색된 콘텐츠는 데이터이지 지시가 아닙니다 — Athenaeum은 LLM을 호출하지 않습니다. 이러한 보장이 무엇에 기반하는지는 THREAT-MODEL.md를, 어디까지 유효한지는 SECURITY-ASSUMPTIONS.md를 참조하세요.

빠른 시작

TOKEN=$(curl -s https://auth.xfeatures.net/oauth/token \
  -d grant_type=client_credentials \
  -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET" | jq -r .access_token)

curl -s https://athenaeum.xfeatures.net/v1/knowledge/search \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"query": "what is the refund window", "domain": "support"}'

전체 실습 가이드: REST · MCP

문서

연결하기

이 저장소가 바로 서비스입니다. 개발자 대상 인터페이스는 각각 별도의 저장소에 있으며, 각자 고유한 README, 예제, 릴리스 주기를 가집니다.

MCP 서버 구현은 여기, src/mcp/에 있습니다. REST 및 Workers RPC와 동일한 authenticate → authorize → audit 파이프라인을 공유하기 때문입니다. MCP 저장소는 클라이언트 측면, 즉 연결 방법과 도구가 하는 일을 다룹니다. REST도 마찬가지로 여기에 구현되어 있습니다 — SDK가 그 클라이언트이므로 별도로 유지할 REST 서버 저장소는 없습니다.

요청이 결정되는 방식

flowchart LR
    req["REST · RPC · MCP"] --> authn["authenticate<br/>introspect or RPC key"]
    authn --> princ["resolve principal<br/>fresh from D1"]
    princ --> authz["authorize<br/>permission + classification + domain"]
    authz --> svc["knowledge services"]
    svc --> live["re-check every result<br/>against the live row"]
    live --> audit["audit the decision"]
    audit --> resp["response"]

세 가지 전송 방식 모두 동일한 코드가 실행됩니다. MCP나 "내부(internal)" 호출자에게 더 느슨한 ACL은 없습니다.

문서 수명 주기

문서는 버전 수준에서 불변입니다. 편집은 새 버전을 작성하며 이력을 다시 쓰지 않습니다. 롤백은 이전 버전을 새 버전으로 다시 게시합니다.

stateDiagram-v2
    [*] --> draft: upload
    draft --> pending_review: submit for review
    pending_review --> active: approved
    pending_review --> draft: rejected
    draft --> active: publish
    active --> deprecated: supersede
    deprecated --> active: republish
    active --> archived: archive
    draft --> trashed: move to trash
    active --> trashed: move to trash
    archived --> trashed: move to trash
    trashed --> draft: restore
    trashed --> active: restore
    trashed --> [*]: scheduled purge after 72h

휴지통은 지연된 삭제 버튼이 아닙니다. 휴지통으로 이동된 문서는 모든 검색 표면에서 즉시 제거됩니다 — HQ, REST, MCP — 그리고 해당 문서에 대한 AI Search 결과는 실시간 데이터베이스 검사에서 거부됩니다. 72시간 후 예약 작업이 표준 콘텐츠와 그 이력 객체를 영구 삭제하지만, 감사 추적은 남아 있습니다.

개발

npm install
npm run typecheck && npm run lint && npm test

테스트는 @cloudflare/vitest-pool-workers를 통해 실제 Workers 런타임 안에서 실행됩니다. 통합 테스트는 실행할 때마다 실제 마이그레이션을 Miniflare 기반 D1에 적용하며, 소스 검사 테스트 세트는 예를 들어 권한 관문 없이 새 관리자 라우트가 추가되면 빌드를 실패시킵니다.

서비스를 로컬에서 실행하려면 LOCAL-DEVELOPMENT.md를 참조하세요.

보안

보안 문제는 공개 이슈로 올리지 말아 주세요 — 비공개 신고는 SECURITY.md를 참조하세요.

핵심 주장은 완전히 손상된 낮은 권한의 에이전트가 유효한 자격 증명을 포함하더라도 자신의 권한 범위를 벗어난 어떤 것도 읽거나 수정하거나 삭제할 수 없고, 더 강력한 신원으로 권한을 상승시킬 수 없다는 것입니다. 위협 모델은 이것이 무엇에 기반하는지 설명하고, SECURITY-ASSUMPTIONS.md는 그 한계가 어디인지 설명합니다.

이 코드베이스는 내부 역공(adversarial) 검토를 거쳤으며, 각 발견 사항에 대한 회귀 테스트는 취약한 코드에 대해 실패하는 것으로 검증되었습니다. 이는 독립적인 침투 테스트를 대체하는 것이 아니며, 시스템에 결함이 없다는 주장도 아닙니다.

구축되지 않은 것

과장된 암시 대신 한계점을 솔직하게 밝힙니다:

• PDF 수집. 검증된 안전한 Worker 내 PDF 텍스트 추출은 연결되어 있지 않습니다. 업스트림에서 Markdown 또는 일반 텍스트로 변환하세요.

• 임시 역할 및 권한 편집. 역할은 완전히 모델링되고 시드되며 에이전트 생성 시 부여되지만, 사후에 이를 편집할 수 있는 CRUD 인터페이스는 없습니다.

• 사실, 제품, 플랜, 서비스 및 정책에 대한 관리자 목록 보기. 생성 및 업데이트는 존재하지만, 페이지네이션된 "유형 X의 모든 항목 나열"은 없습니다.

• 캐싱 계층. 의도적으로 포함하지 않았습니다. AI Search 자체 응답 캐시는 비활성화되어 있는데, 에이전트별 분류 및 도메인 필터에 관한 캐시 키 계약이 문서화되어 있지 않기 때문입니다. 이 계약이 없다면 "한 에이전트의 캐시된 결과가 다른 범위의 에이전트에게 절대 전달될 수 없다"는 것을 증명할 수 없습니다.

• 대량 작업. 대량 게시, 대량 휴지통, 대량 삭제가 없습니다.

라이선스

소스 공개 — 오픈소스가 아닌 독점 소프트웨어입니다.

이 저장소는 MIT, Apache, GPL 또는 OSI 승인 라이선스가 아닌 Xfeatures 독점 소스 라이선스에 따라 라이선스가 부여됩니다. 요약하면 다음과 같습니다:

보안 연구 예외 조항 및 상업용 라이선스 요청 방법을 포함한 전체 약관은 LICENSE에 있습니다.