Uma busca que encontra um documento ao qual o usuário não tem acesso já falhou, ainda que a interface oculte o link final. Em sistemas documentais, processos, backoffices e bases de conhecimento, o risco surge antes: no índice, nos fragmentos recuperados, nos metadados exibidos e em uma resposta gerada a partir de contexto não autorizado.
A busca semântica com permissões em PHP deve tratar a autorização como parte da recuperação, e não como uma verificação decorativa da visualização. O objetivo não é apenas retornar resultados úteis: é garantir que cada fragmento candidato, citação e resposta seja derivado exclusivamente de conteúdo que o principal autenticado pode consultar naquele momento.
Decisões que devem ser definidas antes de indexar
Comece definindo o corpus e seu modelo de acesso. Nem todos os conteúdos têm o mesmo ciclo de vida nem a mesma sensibilidade: uma política pública, um manual interno, um processo e um arquivo compartilhado externamente exigem regras distintas. Também é preciso decidir qual ação habilita a busca: localizar um título, ler um extrato, abrir o documento, baixar um anexo ou solicitar um resumo. Ter permissão de descoberta não implica necessariamente permissão de leitura.
- Principal: usuário, conta de serviço ou sessão delegada que realiza a consulta.
- Escopo: organização, espaço de trabalho, projeto, processo ou repositório onde pode pesquisar.
- Ação: descobrir, ler, baixar ou administrar.
- Recurso: documento e fragmento, com seu estado, classificação e pertencimento.
- Tolerância a erro: na autorização, não revelar deve prevalecer; um falso negativo é incômodo, um falso positivo pode ser uma violação.
A similaridade vetorial não entende regras de negócio. Um embedding representa proximidade de significado, não legitimidade de acesso. Por isso, o projeto não pode confiar que um resultado “semelhante” seja seguro nem que um modelo generativo ignore o contexto indevido.
Arquitetura de referência e fonte de verdade
Mantenha as permissões em uma fonte de verdade transacional: a aplicação PHP, seu banco de dados ou o sistema documental que governa os recursos. O índice é uma projeção recuperável, não a autoridade que decide o acesso. Se o índice for corrompido, atrasar ou receber dados incompletos, a camada de autorização deve conseguir impedir a entrega.
Um fluxo robusto separa quatro etapas:
- O conteúdo é extraído de uma versão identificável do documento e dividido em fragmentos com limites coerentes.
- Representações de recuperação são calculadas e armazenadas junto com metadados de escopo e versão.
- A consulta constrói um filtro autorizável para o principal e recupera candidatos somente dentro desse escopo.
- A aplicação verifica novamente a permissão e a vigência de cada candidato antes de exibi-lo ou usá-lo como contexto.
Em PHP, encapsule essas responsabilidades. Um serviço de políticas deve resolver can($principal, 'read', $documento); um adaptador de índice deve receber filtros derivados dessa decisão; e o montador de resultados deve aceitar somente candidatos verificados. Evite que controladores, templates ou prompts componham filtros de permissões por conta própria.
Metadados que permitem filtrar sem adivinhar
Cada documento e fragmento precisa de um identificador estável de organização e recurso, uma versão de conteúdo, estado de indexação e referência ao documento pai. Adicione os atributos necessários para expressar a política, mas não replique dados sensíveis sem necessidade.
- tenant_id ou organização: barreira obrigatória em ambientes multicliente.
- document_id e chunk_id: rastreabilidade do resultado até a fonte.
- acl_revision: versão da política aplicada durante a indexação.
- audience: escopo simples, como público interno, equipe, projeto ou processo.
- lifecycle_state: ativo, arquivado, excluído ou pendente de revisão.
- content_revision: evita citar uma versão já substituída.
Não indexe uma lista gigantesca de usuários por fragmento se a política se baseia em grupos dinâmicos: isso aumenta o custo, expõe relações e envelhece mal. É preferível filtrar por escopos estáveis quando possível e resolver as exceções na verificação posterior. Se o mecanismo de recuperação não admitir filtros confiáveis, não deve receber conteúdo de vários escopos de segurança no mesmo espaço consultável.
Filtrar antes de recuperar e verificar depois
A filtragem prévia reduz a superfície de exposição: a consulta semântica deve incluir organização, estado ativo e os escopos permitidos antes de calcular os candidatos finais. Assim, evita-se que texto proibido influencie o ranking, os extratos ou o contexto de uma resposta assistida.
A verificação posterior continua sendo necessária. As permissões podem mudar entre a consulta e a leitura, uma herança pode depender de um dado não projetado ou o índice pode estar atrasado. Para cada candidato, recupere o documento atual ou consulte um cache de autorização com invalidação segura. Se a verificação falhar, descarte o fragmento sem revelar seu título, pontuação nem existência.
Quando houver geração assistida, forneça ao modelo somente fragmentos já autorizados e verificados. Defina um caso de uso concreto, como resumir resultados recuperados; avalie respostas com casos permitidos e proibidos; mantenha citações verificáveis; limite o custo por consulta; e mantenha uma alternativa não generativa, como uma lista de resultados. Um modelo não substitui a política de acesso nem o controle humano sobre conteúdos sensíveis.
Herança, links e revogações que quebram projetos simples
Os grupos, as pastas herdadas e os links compartilhados introduzem mudanças indiretas. Uma pessoa que sai de um grupo, um documento que muda de pasta ou um link que expira devem afetar tanto a abertura quanto a recuperação. Modele explicitamente a precedência entre permissões diretas, herança e negações, e teste conflitos.
As revogações exigem uma estratégia mais rigorosa do que as concessões. Publique eventos de mudança de conteúdo e ACL por meio de uma fila transacional ou de um registro de alterações; um worker recalcula metadados e remove ou reindexa fragmentos. Enquanto o índice converge, a verificação posterior protege a entrega. Para exclusões, marque o recurso como indisponível imediatamente na fonte de verdade e elimine seus fragmentos de forma assíncrona, com alertas se o atraso exceder o objetivo operacional.
Resultados verificáveis, testes e observabilidade
Exiba título, extrato limitado, localização e data somente se esses campos também puderem ser lidos. Cada resultado deve levar ao recurso original autorizado; uma citação não deve revelar um caminho, autor ou texto de um documento oculto. Na ausência de resultados, use uma mensagem neutra: não confirme se existe conteúdo fora do escopo do usuário.
Construa uma matriz de testes com usuários de diferentes organizações, membros e não membros de grupos, administradores limitados, links expirados e recursos revogados durante uma sessão. Teste consultas diretas, sinônimos, termos raros e perguntas projetadas para atrair conteúdo proibido. Os resultados esperados incluem listas vazias quando tudo o que é relevante está bloqueado.
Registre, sem armazenar consultas sensíveis desnecessariamente, a versão do índice, os filtros aplicados, o número de candidatos antes e depois da verificação, a latência, as negações e o atraso de sincronização. Um aumento de descartes posteriores pode indicar ACLs desatualizadas; zero resultados após uma migração pode indicar filtros excessivos; consultas entre organizações são um alerta de isolamento.
Quando escolher outra solução e lista de verificação final
A busca semântica nem sempre compensa. Para catálogos pequenos e vocabulário estável, filtros, busca textual e navegação hierárquica são mais explicáveis e baratos. Também são preferíveis quando as permissões são muito dinâmicas e o mecanismo não consegue filtrar por atributos de forma segura. Use recuperação semântica quando ela agregar valor real a consultas formuladas em linguagem natural e for possível sustentar o controle de acesso completo.
- A fonte de verdade decide o acesso e o índice pode ser reconstruído.
- Todos os fragmentos têm organização, documento, versão e estado.
- A consulta filtra antes de recuperar e verifica antes de entregar.
- Concessões, alterações, revogações e exclusões têm sincronização observável.
- As respostas assistidas usam somente contexto autorizado, citações e uma alternativa sem IA.
- Os testes incluem tentativas deliberadas de acesso indevido e resultados vazios.
