nacre CLAUDE.md

Nacre — core

A self-hosted knowledge index with fine-grained access control. Agents reach it over MCP, applications over a REST API. Apache 2.0; the commercial modules live in a separate private repository.

Read docs/authz.md before writing anything. Every other subsystem depends on the permission model, and reworking it after search exists is expensive. Work order is in docs/README.md.

The six invariants

Breaking one of these is a security incident, not a bug. They are not negotiable in a PR.

1. The organization comes from the token — never from a body, path, or header.
2. Access filtering is a pre-filter, never a post-filter. The filter goes inside the index traversal so top_k returns k permitted results.
3. A failure to evaluate permissions denies access. There is no "couldn't compute it, let it through" path.
4. "No permission" and "no such object" are indistinguishable — 404, never 403, including the wording of the message.
5. A deleted document is never returned, including before garbage collection. deleted = false belongs in every query.
6. write does not imply read. admin implies both. This is the opposite of most permission systems; do not "fix" it.

Never, in any change

• Filter search results after they come back from the vector database.
• Accept org_id from a request body, path, or header.
• Return 403 where the object is invisible.
• Log document contents or full query text.
• Ask for a larger top_k and trim on permission — that is a post-filter that also costs more. Trimming on relevance over an already-permitted candidate set is what reranking is, and it is allowed; the test is whether the answer can end up smaller than the number of permitted matches.
• Skip the ACL filter in one branch of a hybrid query. Every prefetch branch carries it; one omission is a leak.
• Query outside withOrg without saying which mechanism permits it. There are two, and only two: whileAuthenticating for resolving a credential, and acrossOrganizations for the worker's queue. A raw pool.connect() that reads a tenant table is a query that works in development and raises in production, because development connects as a superuser and the policies do not apply to one.