Una búsqueda que encuentra un documento al que el usuario no tiene acceso ya ha fallado, aunque la interfaz oculte el enlace final. En sistemas documentales, expedientes, backoffices y bases de conocimiento, el riesgo aparece antes: en el índice, en los fragmentos recuperados, en los metadatos mostrados y en una respuesta generada a partir de contexto no autorizado.
La búsqueda semántica con permisos en PHP debe tratar la autorización como parte de la recuperación, no como una comprobación decorativa de la vista. El objetivo no es sólo devolver resultados útiles: es garantizar que cada fragmento candidato, cita y respuesta se deriva exclusivamente de contenido que el principal autenticado puede consultar en ese momento.
Decisiones que deben cerrarse antes de indexar
Empiece definiendo el corpus y su modelo de acceso. No todos los contenidos tienen el mismo ciclo de vida ni la misma sensibilidad: una política pública, un manual interno, un expediente y un archivo compartido externamente requieren reglas distintas. También debe decidir qué acción habilita la búsqueda: localizar un título, leer un extracto, abrir el documento, descargar un adjunto o pedir un resumen. Tener permiso de descubrimiento no implica necesariamente permiso de lectura.
- Principal: usuario, cuenta de servicio o sesión delegada que realiza la consulta.
- Ámbito: organización, espacio de trabajo, proyecto, expediente o repositorio donde puede buscar.
- Acción: descubrir, leer, descargar o administrar.
- Recurso: documento y fragmento, con su estado, clasificación y pertenencia.
- Tolerancia al error: en autorización debe primar no revelar; un falso negativo es molesto, un falso positivo puede ser una brecha.
La similitud vectorial no entiende reglas de negocio. Un embedding representa proximidad de significado, no legitimidad de acceso. Por eso el diseño no puede confiar en que un resultado “parecido” sea seguro ni en que un modelo generativo ignore el contexto indebido.
Arquitectura de referencia y fuente de verdad
Conserve los permisos en una fuente de verdad transaccional: la aplicación PHP, su base de datos o el sistema documental que gobierna los recursos. El índice es una proyección recuperable, no la autoridad que decide acceso. Si el índice se corrompe, se retrasa o recibe datos incompletos, la capa de autorización debe poder impedir la entrega.
Un flujo robusto separa cuatro etapas:
- Se extrae contenido de una versión identificable del documento y se divide en fragmentos con límites coherentes.
- Se calculan representaciones de recuperación y se guardan junto con metadatos de alcance y versión.
- La consulta construye un filtro autorizable para el principal y recupera candidatos sólo dentro de ese alcance.
- La aplicación vuelve a comprobar permiso y vigencia por cada candidato antes de mostrarlo o usarlo como contexto.
En PHP, encapsule estas responsabilidades. Un servicio de políticas debe resolver can($principal, 'read', $documento); un adaptador de índice debe recibir filtros derivados de esa decisión; y el ensamblador de resultados sólo debe aceptar candidatos verificados. Evite que controladores, plantillas o prompts compongan filtros de permisos por su cuenta.
Metadatos que permiten filtrar sin adivinar
Cada documento y fragmento necesita un identificador estable de organización y recurso, una versión de contenido, estado de indexación y referencia al documento padre. Añada los atributos necesarios para expresar la política, pero no replique datos sensibles sin necesidad.
- tenant_id u organización: barrera obligatoria en entornos multicliente.
- document_id y chunk_id: trazabilidad desde el resultado hasta la fuente.
- acl_revision: versión de la política aplicada al indexar.
- audience: ámbito simple como público interno, equipo, proyecto o expediente.
- lifecycle_state: activo, archivado, eliminado o pendiente de revisión.
- content_revision: evita citar una versión ya sustituida.
No indexe una lista gigantesca de usuarios por fragmento si la política se basa en grupos cambiantes: aumenta coste, expone relaciones y envejece mal. Es preferible filtrar por ámbitos estables cuando sea posible y resolver las excepciones en la verificación posterior. Si el motor de recuperación no admite filtros fiables, no debe recibir contenido de varios ámbitos de seguridad en el mismo espacio consultable.
Filtrar antes de recuperar y verificar después
El filtrado previo reduce la superficie de exposición: la consulta semántica debe incluir organización, estado activo y los ámbitos permitidos antes de calcular los candidatos finales. Así se evita que texto prohibido influya en el ranking, en extractos o en el contexto de una respuesta asistida.
La verificación posterior sigue siendo necesaria. Los permisos pueden cambiar entre la consulta y la lectura, una herencia puede depender de un dato no proyectado o el índice puede estar retrasado. Para cada candidato, recupere el documento actual o consulte una caché de autorización con invalidación segura. Si falla la comprobación, descarte el fragmento sin revelar su título, puntuación ni existencia.
Cuando haya generación asistida, entregue al modelo sólo fragmentos ya autorizados y verificados. Defina un caso de uso concreto, como resumir resultados recuperados; evalúe respuestas con casos permitidos y prohibidos; conserve citas verificables; limite el coste por consulta; y mantenga una alternativa no generativa, como lista de resultados. Un modelo no sustituye la política de acceso ni el control humano sobre contenidos sensibles.
Herencia, enlaces y revocaciones que rompen diseños simples
Los grupos, carpetas heredadas y enlaces compartidos introducen cambios indirectos. Una persona que abandona un grupo, un documento que cambia de carpeta o un enlace que expira deben afectar tanto a la apertura como a la recuperación. Modele explícitamente la precedencia entre permisos directos, herencia y denegaciones, y pruebe conflictos.
Las revocaciones requieren una estrategia más estricta que las altas. Publique eventos de cambio de contenido y ACL mediante una cola transaccional o un registro de cambios; un trabajador recalcula metadatos y elimina o reindexa fragmentos. Mientras el índice converge, la verificación posterior protege la entrega. Para eliminaciones, marque el recurso como no disponible inmediatamente en la fuente de verdad y purgue sus fragmentos de forma asíncrona, con alertas si el retraso supera el objetivo operativo.
Resultados comprobables, pruebas y observabilidad
Muestre título, extracto limitado, ubicación y fecha sólo si esos campos también son legibles. Cada resultado debe llevar al recurso autorizado original; una cita no debe revelar una ruta, autor o texto de un documento oculto. Ante ausencia de resultados, use un mensaje neutral: no confirme si existe contenido fuera del alcance del usuario.
Construya una matriz de pruebas con usuarios de distintas organizaciones, miembros y no miembros de grupos, administradores limitados, enlaces caducados y recursos revocados durante una sesión. Pruebe consultas directas, sinónimos, términos raros y preguntas diseñadas para atraer contenido prohibido. Los resultados esperables incluyen listas vacías cuando todo lo relevante está vetado.
Registre, sin almacenar consultas sensibles innecesariamente, la versión de índice, filtros aplicados, número de candidatos antes y después de verificar, latencia, denegaciones y retraso de sincronización. Un aumento de descartes posteriores puede indicar ACL desactualizadas; cero resultados tras una migración puede señalar filtros excesivos; consultas entre organizaciones son una alerta de aislamiento.
Cuándo elegir otra solución y lista de salida
La búsqueda semántica no siempre compensa. Para catálogos pequeños y vocabulario estable, filtros, búsqueda textual y navegación jerárquica son más explicables y baratos. También son preferibles cuando los permisos son muy dinámicos y el motor no puede filtrar por atributos de forma segura. Use recuperación semántica cuando aporte valor real a consultas formuladas en lenguaje natural y pueda sostenerse el control de acceso completo.
- La fuente de verdad decide acceso y el índice se puede reconstruir.
- Todos los fragmentos tienen organización, documento, versión y estado.
- La consulta filtra antes de recuperar y verifica antes de entregar.
- Altas, cambios, revocaciones y eliminaciones tienen sincronización observable.
- Las respuestas asistidas usan sólo contexto autorizado, citas y una alternativa sin IA.
- Las pruebas incluyen intentos deliberados de acceso indebido y resultados vacíos.
