Xfeatures Athenaeum

La capa de conocimiento segura que conecta aplicaciones, personas y agentes de IA de Xfeatures.

Un servicio autenticado de conocimiento y recuperación para cada aplicación, persona y agente de IA en una organización. Los hechos exactos viven en D1, los documentos en R2, la recuperación semántica se ejecuta a través de Cloudflare AI Search — y nada habla directamente con ninguno de ellos.

Los llamadores hablan REST, Workers RPC o MCP. Athenaeum resuelve quién pregunta y qué se le permite ver en cada llamada, y luego vuelve a comprobar cada resultado contra la base de datos en vivo antes de devolverlo.

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

Código fuente disponible — software propietario, no de código abierto. Puede leer, clonar y evaluar privadamente este código bajo la Licencia de Código Fuente Propietario de Xfeatures. Ejecutarlo como un servicio de producción, operarlo comercialmente o redistribuir una copia modificada requiere permiso escrito por separado. Consulte Licencia a continuación.

Por qué existe

Dale a cada agente su propia base de datos, su propia copia de los documentos y su propio pipeline RAG hecho a mano, y obtienes una base de conocimiento por agente — cada una desactualizada de manera diferente, ninguna con control de acceso. Athenaeum es la alternativa: un corpus, un modelo de permisos, un registro de auditoría y porciones por agente del mismo.

Related MCP server: Volterra Knowledge Engine

Qué garantiza

• La identidad nunca es reclamada por el cliente. Un llamador presenta una credencial; los permisos provienen de la propia base de datos de Athenaeum, basados en la identidad verificada. Editar el alcance de un token no gana nada.

• La clasificación y el dominio se aplican en cada llamada. Un agente de soporte autorizado para support en INTERNAL no puede ver un documento RESTRICTED archivado bajo el mismo dominio — y nunca se entera de que existe.

• El índice de búsqueda no es autoritativo. Cada fragmento recuperado se vuelve a validar contra la fila de la base de datos en vivo antes de devolverse, por lo que un índice desactualizado o manipulado no puede liberar contenido, y una versión superada no puede servirse bajo la identidad de la actual.

• El conocimiento recuperado es evidencia, no instrucción. Athenaeum nunca llama a un LLM. Devuelve pasajes con citas; el agente llamador sintetiza la respuesta y es responsable de tratar ese contenido como no confiable.

• Publicar requiere un humano. Un agente puede redactar un documento y enviarlo para revisión. Ningún transporte expone una forma de publicarlo.

• Nada se elimina a mano. Los documentos se mueven a la papelera, son restaurables durante 72 horas y se purgan mediante un trabajo programado — nunca mediante un botón.

Dos tipos de conocimiento

Athenaeum almacena hechos exactos y conocimiento semántico de manera diferente, porque fallan de manera diferente.

Un agente que necesita un precio nunca debería buscar uno. Un número que debe ser correcto es una búsqueda de hecho; un pasaje que una persona leerá es un documento. Obtener un precio incorrecto con apariencia plausible de una búsqueda de similitud es exactamente el fallo que esta división existe para prevenir.

Para qué sirve cada almacén

• D1 es la autoridad. Hechos, metadatos de documentos, el catálogo, agentes, roles, permisos, cuotas y el registro de auditoría. Cada decisión de acceso se toma desde D1, nunca desde una caché y nunca desde el índice.

• R2 contiene el contenido canónico de los documentos, un objeto inmutable por versión. Las claves son generadas por el servidor e incorporan clasificación y dominio para la navegabilidad humana — explícitamente no son un límite de seguridad, porque el bucket nunca es accesible públicamente.

• AI Search es un índice sobre R2, y nada más. Es una pista sobre dónde mirar. Nunca es la autoridad sobre lo que un llamador puede ver.

Dónde se sitúa 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 es la plataforma de identidad para el ecosistema Xfeatures. Responde quién llama y nada más: Athenaeum toma la identidad inspeccionada y resuelve permisos desde su propia base de datos. Un token de Account puede demostrar quién eres y aun así no obtener nada aquí. (Account es un sistema separado y privado; este repositorio documenta el contrato público que expone — introspección RFC 7662 — no su implementación.)

• Xfeatures HQ es el plano de control donde las personas administran documentos, revisan y publican, y gestionan el acceso. HQ no tiene estatus especial dentro de Athenaeum — se autentica con su propia credencial de máquina y está autorizado en cada llamada. Revocar el principal de HQ lo corta sin tocar su identidad de Account.

El modelo de seguridad

Cinco propiedades, cada una aplicada en código en lugar de por convención:

1. La identidad se resuelve, nunca se acepta. Los permisos provienen de una lectura fresca de D1 basada en una identidad verificada, en cada llamada. Nada que un llamador envíe puede ampliar lo que puede ver.

2. Dos puertas independientes en cada lectura. Un permiso de alcance (documents.read.<domain>) y un permiso de clasificación (knowledge.classification.<TIER>). Tener uno sin el otro deniega.

3. La procedencia se registra, no se infiere. Cada documento lleva su tipo de fuente y referencia, cada versión registra quién la escribió y por qué, y cada llamada autenticada — permitida o denegada — escribe un evento de auditoría.

4. Las versiones son inmutables. Editar añade una versión; nunca reescribe una. La reversión republica una versión anterior como una nueva versión. El historial es evidencia, por lo que nada lo sobrescribe.

5. Reconciliación de versión actual. Un resultado de búsqueda solo se sirve si el objeto fuente del fragmento es la versión actual del documento y la fila en vivo aún dice que está activo y aún lleva una clasificación que el llamador puede ver. Un índice desactualizado no puede liberar una versión superada bajo la identidad de la actual, y no puede liberar algo archivado, reclasificado o enviado a la papelera hace un momento.

El contenido recuperado es datos, nunca instrucción — Athenaeum nunca llama a un LLM. Consulte THREAT-MODEL.md para ver en qué se basan estas garantías, y SECURITY-ASSUMPTIONS.md para ver dónde terminan.

Inicio rápido

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"}'

Guías completas: REST · MCP

Documentación

Cómo conectarse

Este repositorio es el servicio. Las superficies orientadas al desarrollador viven en sus propios repositorios, por lo que cada uno tiene su propio README, ejemplos y cadencia de lanzamiento:

La implementación del servidor MCP permanece aquí, en src/mcp/, porque comparte un pipeline de autenticar → autorizar → auditar con REST y Workers RPC. El repositorio MCP es la mitad orientada al cliente: cómo conectarse y qué hacen las herramientas. REST también se implementa aquí — el SDK es su cliente, por lo que no hay un repositorio de servidor REST separado que mantener.

Cómo se decide una solicitud

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"]

El mismo código se ejecuta para los tres transportes. No hay una ACL más flexible para MCP o para llamadores "internos".

Ciclo de vida del documento

Los documentos son inmutables a nivel de versión. Editar escribe una nueva versión; nunca reescribe el historial. La reversión republica una versión anterior como una nueva.

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

La papelera no es un botón de eliminar con retraso. Un documento enviado a la papelera abandona inmediatamente toda superficie de recuperación — HQ, REST, MCP — y cualquier resultado de AI Search para él es rechazado por la verificación de la base de datos en vivo. Después de 72 horas, un trabajo programado purga el contenido canónico y sus objetos históricos, mientras que el registro de auditoría permanece.

Desarrollo

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

Las pruebas se ejecutan dentro del runtime real de Workers a través de @cloudflare/vitest-pool-workers. Las pruebas de integración aplican las migraciones reales a un D1 respaldado por Miniflare en cada ejecución, y un conjunto de pruebas de inspección de código fuente falla la compilación si, por ejemplo, se agrega una nueva ruta de administración sin una puerta de permisos.

Para ejecutar el servicio localmente, consulte LOCAL-DEVELOPMENT.md.

Seguridad

Por favor, no abra un problema público para un problema de seguridad — consulte SECURITY.md para informes privados.

La afirmación central es que un agente de bajo privilegio completamente comprometido, con todas sus credenciales válidas, sigue sin poder leer, modificar o destruir nada fuera de su propio conjunto de permisos, y no puede escalar a una identidad más fuerte. El modelo de amenazas indica en qué se basa esto; SECURITY-ASSUMPTIONS.md indica dónde se detiene.

Esta base de código ha pasado por una revisión interna de adversarios, con una prueba de regresión para cada hallazgo verificada para que falle contra el código vulnerable. Eso no sustituye a una prueba de penetración independiente, y no es una afirmación de que el sistema esté libre de defectos.

Lo que no está construido

Siendo directos sobre los límites, en lugar de insinuar más de lo que hay:

• Ingesta de PDF. No hay extracción de texto de PDF verificada como segura dentro del Worker; convierte a Markdown o texto plano en un paso previo.

• Edición ad hoc de roles y permisos. Los roles están completamente modelados y sembrados, y la creación de agentes los otorga, pero no existe una superficie de edición (CRUD) para modificarlos después.

• Vistas de administración para hechos, productos, planes, servicios y políticas. Existen crear y actualizar; no existe una lista paginada de "todos los elementos de tipo X".

• Capa de caché. Ausente deliberadamente. La caché de respuestas propia de la búsqueda de IA está deshabilitada, porque su contrato de clave de caché con respecto a la clasificación por agente y los filtros de dominio no está documentado — y sin eso, "el resultado en caché de un agente nunca puede llegar a un agente con otro ámbito" no es demostrable.

• Operaciones masivas. No hay publicación, eliminación ni vaciado masivo.

Licencia

Código fuente disponible — software propietario, no de código abierto.

Este repositorio está bajo la Licencia de Código Fuente Propietario Xfeatures, no bajo MIT, Apache, GPL ni ninguna licencia aprobada por OSI. En resumen:

Los términos completos, incluida la excepción para investigación de seguridad y cómo solicitar una licencia comercial, están en LICENSE.